Skip to content

Latest commit

 

History

History
594 lines (444 loc) · 17.7 KB

index.md

File metadata and controls

594 lines (444 loc) · 17.7 KB
title description toc_max_heading_level tags
Engine API
Engine API methods reference
3
public networks

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Engine API methods

Consensus and execution clients communicate with each other using the Engine API. When running Besu as an execution client, use these API calls to communicate with a consensus client.

:::info

The engine API is enabled by default.

:::

See the Ethereum Engine API specification for more information. Not all changes to the Engine API are documented on this page.

Methods

engine_exchangeCapabilities

Exchanges a list of supported Engine API methods between the consensus client and Besu.

Parameters

remoteCapabilities: array of strings - Engine API method names that the consensus client supports

Returns

localCapabilities: array of strings - Engine API method names that Besu supports

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_exchangeCapabilities","params":[["engine_exchangeTransitionConfigurationV1","engine_forkchoiceUpdatedV1","engine_getPayloadBodiesByHash","engine_getPayloadBodiesByRangeV1","engine_getPayloadV1","engine_newPayloadV1"]],"id":67}' http://127.0.0.1:8550
{
  "jsonrpc": "2.0",
  "method": "engine_exchangeCapabilities",
  "params": [
    [
      "engine_exchangeTransitionConfigurationV1",
      "engine_forkchoiceUpdatedV1",
      "engine_getPayloadBodiesByHash",
      "engine_getPayloadBodiesByRangeV1",
      "engine_getPayloadV1",
      "engine_newPayloadV1"
    ]
  ],
  "id": 67
}
{
  "jsonrpc": "2.0",
  "id": 67,
  "result": [
    "engine_getPayloadV1",
    "engine_getPayloadV2",
    "engine_executePayloadV1",
    "engine_newPayloadV1",
    "engine_newPayloadV2",
    "engine_forkchoiceUpdatedV1",
    "engine_forkchoiceUpdatedV2",
    "engine_exchangeTransitionConfigurationV1",
    "engine_getPayloadBodiesByHashV1",
    "engine_getPayloadBodiesByRangeV1"
  ]
}

engine_exchangeTransitionConfigurationV1

Sends the transition configuration to the consensus client to verify the configuration between both clients.

:::note

The execution client runs this call every 60 seconds in the background. The log displays a warning message if the call hasn't been sent in 120 seconds.

:::

Parameters

transitionConfiguration: object - Transition configuration object

Returns

transitionConfiguration: object - Transition configuration object

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_exchangeTransitionConfigurationV1","params":[{"terminalTotalDifficulty": 0, "terminalBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000", "terminalBlockNumber": "0x1"}],"id":67}' http://127.0.0.1:8550
{
  "jsonrpc": "2.0",
  "method": "engine_exchangeTransitionConfigurationV1",
  "params": [
    {
      "terminalTotalDifficulty": 0,
      "terminalBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "terminalBlockNumber": "0x1"
    }
  ],
  "id": 67
}
{
  "jsonrpc": "2.0",
  "id": 67,
  "result": {
    "terminalTotalDifficulty": 0,
    "terminalBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "terminalBlockNumber": "0x1"
  }
}

engine_forkchoiceUpdatedV1

Updates the fork choice with the consensus client.

Parameters

Returns

  • payloadStatus: object - Payload status object

  • payloadId: data - identifier of the payload build process or null

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
{
  "jsonrpc": "2.0",
  "method": "engine_forkchoiceUpdatedV1",
  "params": [
    {
      "headBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858",
      "safeBlockHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858",
      "finalizedBlockHash": "0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a"
    },
    null
  ],
  "id": 67
}
{
  "jsonrpc": "2.0",
  "id": 67,
  "result": {
    "payloadStatus": {
      "status": "VALID",
      "latestValidHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858",
      "validationError": null
    },
    "payloadId": null
  }
}

engine_getBlobsV1

Returns the blobs corresponding to the specified blob versioned hashes.

Parameters

versionedHashes: array of strings - Array of blob versioned hashes

Returns

engineGetBlobsResultV1: array of objects - Array of blob and proof objects, items of which can be null

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getBlobsV1","params":[["0x010657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014","0x01f3a5c9d8e7b6a4c2d1e0f9b8a7c6d5e4f3a2b1c0d9e8f7b6a5c4d3e2f1a0b9"]],"id":1}' http://127.0.0.1:8550
{
  "jsonrpc": "2.0",
  "method": "engine_getBlobsV1",
  "params": [
    [
      "0x010657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c444014",
      "0x01f3a5c9d8e7b6a4c2d1e0f9b8a7c6d5e4f3a2b1c0d9e8f7b6a5c4d3e2f1a0b9"
    ]
  ],
  "id": 67
}
{
  "jsonrpc": "2.0",
  "id": 67,
  "result": [
    {
      "blob": "0x722662154e6d76b2b2b92e70c0cac3ccf534f9b74eb5b89819ec509083d00a503ae5c198d17634e79059c2cd735491...",
      "proof": "0x80c5f2e1eb23939cf3600f61872e3e9964d0acafb440634e530d6139a193b889c56a0c07d737729dbe0626706fc9f25f"
    },
    null
  ]
}

engine_getPayloadBodiesByHashV1

Returns the bodies of the execution payloads corresponding to the specified block hashes.

Parameters

blockHashes: array of strings - Block hashes

Returns

engineGetPayloadBodiesResultV1: array of objects - Execution payload body objects

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadBodiesByHashV1","params":[["0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c","0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"]],"id":1}' http://127.0.0.1:8550
{
  "jsonrpc": "2.0",
  "method": "engine_getPayloadBodiesByHashV1",
  "params": [
    [
      "0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c",
      "0xfe88c94d860f01a17f961bf4bdfb6e0c6cd10d3fda5cc861e805ca1240c58553"
    ]
  ],
  "id": 67
}
{
    "jsonrpc": "2.0",
    "id": 67,
    "result": [{
      "transactions": ["0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65", "0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95", ...],
      "withdrawals": [{
        "index" : "0xf0",
        "validatorIndex" : "0xf0",
        "address" : "0x00000000000000000000000000000000000010f0",
        "amount" : "0x1"
      }, {
        "index" : "0xf1",
        "validatorIndex" : "0xf1",
        "address" : "0x00000000000000000000000000000000000010f1",
        "amount" : "0x1"
      }]
    }, {
      "transactions": ["0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe", "0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29", ...],
      "withdrawals": [{
        "index" : "0xf2",
        "validatorIndex" : "0xf2",
        "address" : "0x00000000000000000000000000000000000010f2",
        "amount" : "0x1"
      }, {
        "index" : "0xf3",
        "validatorIndex" : "0xf3",
        "address" : "0x00000000000000000000000000000000000010f3",
        "amount" : "0x1"
      }]
    }]
}

engine_getPayloadBodiesByRangeV1

Returns the bodies of the execution payloads corresponding to the specified range of block numbers.

Parameters

  • startBlockNumber: string - Number of the starting block of the range, as a hexadecimal string

  • count: string - Number of blocks in the range (including the starting block), as a hexadecimal string

Returns

engineGetPayloadBodiesResultV1: array of objects - Execution payload body objects

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadBodiesByRangeV1","params":["0x20", "0x2"],"id":1}' http://127.0.0.1:8550
{
  "jsonrpc": "2.0",
  "method": "engine_getPayloadBodiesByRangeV1",
  "params": ["0x20", "0x2"],
  "id": 67
}
{
    "jsonrpc": "2.0",
    "id": 67,
    "result": [{
      "transactions": ["0xf865808506fc23ac00830124f8940101010101010101010101010101010101010101018031a02c4d88bfdc2f6dbf82c33d235c4e785e9fc23b2d0fc7b9d20fc5e9674f1f9d15a016d6d69b925cf26128683ab4a096e196fbb1142d6c6d4e8d3481b9bef1bd0f65", "0x02f86c0701843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a039409b4e5603dd8c3cf38232348661a8e99ac518396eeaa128ec9ec2a3eb8127a06b21ab956f5f138cb44fda1a9055bd08980ea4f8040d877c00dac025608d0d95", ...],
      "withdrawals": [{
        "index" : "0xf0",
        "validatorIndex" : "0xf0",
        "address" : "0x00000000000000000000000000000000000010f0",
        "amount" : "0x1"
      }, {
        "index" : "0xf1",
        "validatorIndex" : "0xf1",
        "address" : "0x00000000000000000000000000000000000010f1",
        "amount" : "0x1"
      }]
    }, {
      "transactions": ["0xf865108506fc23ac00830124f8940101010101010101010101010101010101010101018031a0d9712a3c40ae85aea4ad1bd95a0b7cc7bd805189a9e2517403b11a00a1530f81a053b53b0267a6dcfe9f9a1652307b396b3e8a65e65707a450e60c92baefdbcfbe", "0x02f86c0711843b9aca008506fc23ac00830124f89402020202020202020202020202020202020202020180c080a071d36bc93c7ae8cc5c01501e51e5e97a51aa541d1a89c809a2af7eb40e9bc2cba071644230e21c075c1da08916aff5efe9f95a6f6a4f94dc217f6c1bb4a3240b29", ...],
      "withdrawals": [{
        "index" : "0xf2",
        "validatorIndex" : "0xf2",
        "address" : "0x00000000000000000000000000000000000010f2",
        "amount" : "0x1"
      }, {
        "index" : "0xf3",
        "validatorIndex" : "0xf3",
        "address" : "0x00000000000000000000000000000000000010f3",
        "amount" : "0x1"
      }]
    }]
}

engine_getPayloadV1

Prepares the payload to send to the consensus client.

Parameters

payloadId: data - Identifier of the payload build process

Returns

executionPayload: object - Execution payload object

curl -X POST --data '{"jsonrpc":"2.0","method":"engine_getPayloadV1","params":["0x0000000021f32cc1"],"id":1}' http://127.0.0.1:8550
{
  "jsonrpc": "2.0",
  "method": "engine_getPayloadV1",
  "params": ["0x0000000021f32cc1"],
  "id": 67
}
{
  "jsonrpc": "2.0",
  "id": 67,
  "result": {
    "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": []
  }
}

engine_newPayloadV1

Executes the payload with the consensus client.

Parameters

executionPayload: object - Execution payload object

Returns

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
{
  "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
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "VALID",
    "latestValidHash": "0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858",
    "validationError": null
  }
}