Skip to main content

Use the Engine API

Consensus and execution clients communicate with each other using the Engine API. These API methods are a separate subsection of the JSON-RPC API.

Configure the Engine API

To configure the Engine API:

Example Engine API configuration
besu --engine-rpc-enabled --rpc-http-enabled --engine-rpc-port=8551 --engine-host-allowlist=localhost,127.0.0.1 --engine-jwt-secret=jwt.hex

Enable the Engine API

Enable the Engine API with the --engine-rpc-enabled CLI option.

note

The --engine-rpc-enabled CLI option enables the Engine API even if no consensus client configuration exists.

Service ports

To specify the port the Engine API service listens on for HTTP and WebSocket, use the --engine-rpc-port option. The default is 8551.

Host allowlist

To prevent DNS rebinding attacks, Besu checks incoming HTTP request host headers, WebSocket connections, and GraphQL requests. Besu accepts requests only when hostnames specified using the --engine-host-allowlist option matches the request host headers. By default, Besu accepts requests and connections from localhost and 127.0.0.1.

info

This isn't a permissioning feature. To restrict access to the Engine API, we recommend using authentication.

If your application publishes RPC ports, specify the hostnames when starting Besu.

Specify * for --engine-host-allowlist to effectively disable host protection.

caution

We don't recommend specifying * for --engine-host-allowlist in production.

Authentication

By default, authentication for the Engine API is enabled. To disable, set the --engine-jwt-disabled option to true.

caution

Don't disable JWT authentication in production environments.

Disable only for testing purposes.

Set the JWT secret by using the --engine-jwt-secret option.

Send a payload using the Engine API

1. Prepare a payload

Prepare to send a payload using engine_forkchoiceUpdatedV1.

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_forkchoiceUpdatedV1","params":[{"headBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", "safeBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a", "finalizedBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000"},{"timestamp": "0x5","prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000","suggestedFeeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b"}],"id":67}' http://127.0.0.1:8550

2. Get the payload

Get the payload using engine_getPayloadV1

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params":["0x1"],"id":1}' http://127.0.0.1:8550

3. Execute the payload

Execute the payload using engine_newPayloadV1

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_newPayloadV1","params":[
{
"parentHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a",
"feeRecipient": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
"stateRoot": "0xca3149fa9e37db08d1cd49c9061db1002ef1cd58db2210f2115c8c989b2bdf45",
"receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"prevRandao": "0x0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": "0x1",
"gasLimit": "0x1c9c380",
"gasUsed": "0x0",
"timestamp": "0x5",
"extraData": "0x",
"baseFeePerGas": "0x7",
"blockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858",
"transactions": []
}
],"id":67}' http://127.0.0.1:8550

4. Update the fork choice

Update the fork choice using engine_forkchoiceUpdatedV1 again.

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_forkchoiceUpdatedV1","params":[{"headBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", "safeBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858", "finalizedBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a"},null],"id":67}' http://127.0.0.1:8550