diff --git a/src/engine/specification.md b/src/engine/specification.md index 3cd6d6ee..ed0011c3 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -197,7 +197,7 @@ This structure contains the attributes required to initiate a payload build proc 3. Client software **MUST** return `SYNCING` status if the payload identified by either the `headBlockHash` or the `finalizedBlockHash` is unknown or if the sync process is in progress. In the event that either the `headBlockHash` or the `finalizedBlockHash` is unknown, the client software **SHOULD** initiate the sync process. 4. Client software **MUST** begin a payload build process building on top of `headBlockHash` if `payloadAttributes` is not `null` and the client is not `SYNCING`. The build process is specified as: - * The payload build process **MUST** be identifid via `payloadId` where `payloadId` is defined as the first `8` bytes of the `sha256` hash of concatenation of `headBlockHash`, `payloadAttributes.timestamp`, `payloadAttributes.random`, and `payloadAttributes.feeRecipient` where `payloadAttributes.timestamp` is encoded as big-endian and padded fully to 8 bytes -- i.e. `sha256(headBlockHash + timestamp + random + feeRecipient)[0:8]`. + * The payload build process **MUST** be identified via `payloadId` where `payloadId` is defined as the hash of the block-production inputs, see [Hashing to `payloadId`](#hashing-to-payloadid). * Client software **MUST** set the payload field values according to the set of parameters passed into this method with exception of the `feeRecipient`. The prepared `ExecutionPayload` **MAY** deviate the `coinbase` field value from what is specified by the `feeRecipient` parameter. * Client software **SHOULD** build the initial version of the payload which has an empty transaction set. * Client software **SHOULD** start the process of updating the payload. The strategy of this process is implementation dependent. The default strategy is to keep the transaction set up-to-date with the state of local mempool. @@ -205,13 +205,26 @@ This structure contains the attributes required to initiate a payload build proc 5. If any of the above fails due to errors unrelated to the client software's normal `SYNCING` status, the client software **MUST** return an error. +##### Hashing to `payloadId` + +The `payloadId` is the `sha256` hash of the concatenation of version byte and inputs: +```python +PAYLOAD_ID_VERSION_BYTE = b"\x00" +sha256(PAYLOAD_ID_VERSION_BYTE + headBlockHash + payloadAttributes.timestamp.to_bytes(8, "big") + payloadAttributes.random + payloadAttributes.feeRecipient) +``` +Note that the timestamp is encoded as big-endian and padded fully to 8 bytes. + +This ID-computation is versioned and may change over time, opaque to the engine API user, and **MUST** always be consistent between `engine_forkchoiceUpdated` and `engine_getPayload`. +The `PAYLOAD_ID_VERSION_BYTE` **SHOULD** be updated if the intent or typing of the payload production inputs changes, +such that a payload cache can be safely shared between current and later versions of `engine_forkchoiceUpdated`. + ### engine_getPayloadV1 #### Request * method: `engine_getPayloadV1` * params: - 1. `payloadId`: `DATA`, 8 bytes - Identifier of the payload build process + 1. `payloadId`: `DATA`, 32 bytes - Identifier of the payload build process #### Response