Merge pull request #172 from mkalinin/transition-config
Engine API: add getTransitionConfiguration
This commit is contained in:
Danny Ryan
GitHub
commit
3628b886fc
|
|
@ -17,6 +17,7 @@ This document specifies the Engine API methods that the Consensus Layer uses to
|
|||
- [ForkchoiceStateV1](#forkchoicestatev1)
|
||||
- [PayloadAttributesV1](#payloadattributesv1)
|
||||
- [PayloadStatusV1](#payloadstatusv1)
|
||||
- [TransitionConfigurationV1](#transitionconfigurationv1)
|
||||
- [Routines](#routines)
|
||||
- [Payload validation](#payload-validation)
|
||||
- [Sync](#sync)
|
||||
|
|
@ -34,6 +35,10 @@ This document specifies the Engine API methods that the Consensus Layer uses to
|
|||
- [Request](#request-2)
|
||||
- [Response](#response-2)
|
||||
- [Specification](#specification-2)
|
||||
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
|
||||
- [Request](#request-3)
|
||||
- [Response](#response-3)
|
||||
- [Specification](#specification-3)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
|
|
@ -168,6 +173,13 @@ This structure contains the result of processing a payload. The fields are encod
|
|||
- `latestValidHash`: `DATA|null`, 32 Bytes - the hash of the most recent *valid* block in the branch defined by payload and its ancestors
|
||||
- `validationError`: `String|null` - a message providing additional details on the validation error if the payload is deemed `INVALID`
|
||||
|
||||
### TransitionConfigurationV1
|
||||
|
||||
This structure contains configurable settings of the transition process. The fields are encoded as follows:
|
||||
- `terminalTotalDifficulty`: `QUANTITY`, 256 Bits - maps on the `TERMINAL_TOTAL_DIFFICULTY` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration)
|
||||
- `terminalBlockHash`: `DATA`, 32 Bytes - maps on `TERMINAL_BLOCK_HASH` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration)
|
||||
- `terminalBlockNumber`: `QUANTITY`, 64 Bits - maps on `TERMINAL_BLOCK_NUMBER` parameter of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration)
|
||||
|
||||
## Routines
|
||||
|
||||
### Payload validation
|
||||
|
|
@ -176,23 +188,23 @@ Payload validation process consists of validating a payload with respect to the
|
|||
|
||||
1. Client software **MAY** obtain a parent state by executing ancestors of a payload as a part of the validation process. In this case each ancestor **MUST** also pass payload validation process.
|
||||
|
||||
1. Client software **MUST** validate that the most recent PoW block in the chain of a payload ancestors satisfies terminal block conditions according to [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#transition-block-validity). This check maps to the transition block validity section of the EIP. If this validation fails, the response **MUST** contain `{status: INVALID_TERMINAL_BLOCK, latestValidHash: null}`. Additionally, each block in a tree of descendants of an invalid terminal block **MUST** be deemed `INVALID`.
|
||||
2. Client software **MUST** validate that the most recent PoW block in the chain of a payload ancestors satisfies terminal block conditions according to [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#transition-block-validity). This check maps to the transition block validity section of the EIP. If this validation fails, the response **MUST** contain `{status: INVALID_TERMINAL_BLOCK, latestValidHash: null}`. Additionally, each block in a tree of descendants of an invalid terminal block **MUST** be deemed `INVALID`.
|
||||
|
||||
1. Client software **MUST** validate a payload according to the block header and execution environment rule set with modifications to these rule sets defined in the [Block Validity](https://eips.ethereum.org/EIPS/eip-3675#block-validity) section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#specification):
|
||||
3. Client software **MUST** validate a payload according to the block header and execution environment rule set with modifications to these rule sets defined in the [Block Validity](https://eips.ethereum.org/EIPS/eip-3675#block-validity) section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#specification):
|
||||
* If validation succeeds, the response **MUST** contain `{status: VALID, latestValidHash: payload.blockHash}`
|
||||
* If validation fails, the response **MUST** contain `{status: INVALID, latestValidHash: validHash}` where `validHash` is the block hash of the most recent *valid* ancestor of the invalid payload. That is, the valid ancestor of the payload with the highest `blockNumber`
|
||||
* Client software **MUST NOT** surface an `INVALID` payload over any API endpoint and p2p interface.
|
||||
|
||||
1. Client software **MAY** provide additional details on the validation error if a payload is deemed `INVALID` by assigning the corresponding message to the `validationError` field.
|
||||
4. Client software **MAY** provide additional details on the validation error if a payload is deemed `INVALID` by assigning the corresponding message to the `validationError` field.
|
||||
|
||||
1. The process of validating a payload on the canonical chain **MUST NOT** be affected by an active sync process on a side branch of the block tree. For example, if side branch `B` is `SYNCING` but the requisite data for validating a payload from canonical branch `A` is available, client software **MUST** run full validation of the payload and respond accordingly.
|
||||
5. The process of validating a payload on the canonical chain **MUST NOT** be affected by an active sync process on a side branch of the block tree. For example, if side branch `B` is `SYNCING` but the requisite data for validating a payload from canonical branch `A` is available, client software **MUST** run full validation of the payload and respond accordingly.
|
||||
|
||||
### Sync
|
||||
|
||||
In the context of this specification, the sync is understood as the process of obtaining data required to validate a payload. The sync process may consist of the following stages:
|
||||
|
||||
1. Pulling data from remote peers in the network.
|
||||
1. Passing ancestors of a payload through the [Payload validation](#payload-validation) and obtaining a parent state.
|
||||
2. Passing ancestors of a payload through the [Payload validation](#payload-validation) and obtaining a parent state.
|
||||
|
||||
*Note:* Each of these stages is optional. Exact behavior of client software during the sync process is implementation dependent.
|
||||
|
||||
|
|
@ -202,11 +214,11 @@ The payload build process is specified as follows:
|
|||
|
||||
1. Client software **MUST** set the payload field values according to the set of parameters passed into this method with exception of the `suggestedFeeRecipient`. The built `ExecutionPayload` **MAY** deviate the `feeRecipient` field value from what is specified by the `suggestedFeeRecipient` parameter.
|
||||
|
||||
1. Client software **SHOULD** build the initial version of the payload which has an empty transaction set.
|
||||
2. Client software **SHOULD** build the initial version of the payload which has an empty transaction set.
|
||||
|
||||
1. 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.
|
||||
3. 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.
|
||||
|
||||
1. Client software **SHOULD** stop the updating process when either a call to `engine_getPayload` with the build process's `payloadId` is made or [`SECONDS_PER_SLOT`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#time-parameters-1) (12s in the Mainnet configuration) have passed since the point in time identified by the `timestamp` parameter.
|
||||
4. Client software **SHOULD** stop the updating process when either a call to `engine_getPayload` with the build process's `payloadId` is made or [`SECONDS_PER_SLOT`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#time-parameters-1) (12s in the Mainnet configuration) have passed since the point in time identified by the `timestamp` parameter.
|
||||
|
||||
## Core
|
||||
|
||||
|
|
@ -227,13 +239,13 @@ The payload build process is specified as follows:
|
|||
|
||||
1. Client software **MUST** validate `blockHash` value as being equivalent to `Keccak256(RLP(ExecutionBlockHeader))`, where `ExecutionBlockHeader` is the execution layer block header (the former PoW block header structure). Fields of this object are set to the corresponding payload values and constant values according to the Block structure section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#block-structure), extended with the corresponding section of [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399#block-structure). Client software **MUST** run this validation in all cases even if this branch or any other branches of the block tree are in an active sync process.
|
||||
|
||||
1. Client software **MAY** initiate a sync process if requisite data for payload validation is missing. Sync process is specified in the [Sync](#sync) section.
|
||||
2. Client software **MAY** initiate a sync process if requisite data for payload validation is missing. Sync process is specified in the [Sync](#sync) section.
|
||||
|
||||
1. Client software **MUST** validate the payload if it extends the canonical chain and requisite data for the validation is locally available. The validation process is specified in the [Payload validation](#payload-validation) section.
|
||||
3. Client software **MUST** validate the payload if it extends the canonical chain and requisite data for the validation is locally available. The validation process is specified in the [Payload validation](#payload-validation) section.
|
||||
|
||||
1. Client software **MAY NOT** validate the payload if the payload doesn't belong to the canonical chain.
|
||||
4. Client software **MAY NOT** validate the payload if the payload doesn't belong to the canonical chain.
|
||||
|
||||
1. Client software **MUST** respond to this method call in the following way:
|
||||
5. Client software **MUST** respond to this method call in the following way:
|
||||
* `{status: INVALID_BLOCK_HASH, latestValidHash: null, validationError: errorMessage | null}` if the `blockHash` validation has failed
|
||||
* `{status: INVALID_TERMINAL_BLOCK, latestValidHash: null, validationError: errorMessage | null}` if terminal block conditions are not satisfied
|
||||
* `{status: SYNCING, latestValidHash: null, validationError: null}` if the payload extends the canonical chain and requisite data for its validation is missing
|
||||
|
|
@ -243,7 +255,7 @@ The payload build process is specified as follows:
|
|||
- the payload doesn't extend the canonical chain
|
||||
- the payload hasn't been fully validated.
|
||||
|
||||
1. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
|
||||
6. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
|
||||
|
||||
### engine_forkchoiceUpdatedV1
|
||||
|
||||
|
|
@ -269,26 +281,26 @@ The payload build process is specified as follows:
|
|||
|
||||
1. Client software **MAY** initiate a sync process if `forkchoiceState.headBlockHash` references an unknown payload or a payload that can't be validated because data that are requisite for the validation is missing. The sync process is specified in the [Sync](#sync) section.
|
||||
|
||||
1. Client software **MAY** skip an update of the forkchoice state and **MUST NOT** begin a payload build process if `forkchoiceState.headBlockHash` doesn't reference a leaf of the block tree. That is, the block referenced by `forkchoiceState.headBlockHash` is neither the head of the canonical chain nor a block at the tip of any other chain.
|
||||
2. Client software **MAY** skip an update of the forkchoice state and **MUST NOT** begin a payload build process if `forkchoiceState.headBlockHash` doesn't reference a leaf of the block tree. That is, the block referenced by `forkchoiceState.headBlockHash` is neither the head of the canonical chain nor a block at the tip of any other chain.
|
||||
|
||||
1. If `forkchoiceState.headBlockHash` references a PoW block, client software **MUST** validate this block with respect to terminal block conditions according to [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#transition-block-validity). This check maps to the transition block validity section of the EIP. Additionally, if this validation fails, client software **MUST NOT** update the forkchoice state and **MUST NOT** begin a payload build process.
|
||||
3. If `forkchoiceState.headBlockHash` references a PoW block, client software **MUST** validate this block with respect to terminal block conditions according to [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#transition-block-validity). This check maps to the transition block validity section of the EIP. Additionally, if this validation fails, client software **MUST NOT** update the forkchoice state and **MUST NOT** begin a payload build process.
|
||||
|
||||
1. Before updating the forkchoice state, client software **MUST** ensure the validity of the payload referenced by `forkchoiceState.headBlockHash`, and **MAY** validate the payload while processing the call. The validation process is specified in the [Payload validation](#payload-validation) section.
|
||||
4. Before updating the forkchoice state, client software **MUST** ensure the validity of the payload referenced by `forkchoiceState.headBlockHash`, and **MAY** validate the payload while processing the call. The validation process is specified in the [Payload validation](#payload-validation) section.
|
||||
|
||||
1. Client software **MUST** update its forkchoice state if payloads referenced by `forkchoiceState.headBlockHash` and `forkchoiceState.finalizedBlockHash` are `VALID`. The update is specified as follows:
|
||||
5. Client software **MUST** update its forkchoice state if payloads referenced by `forkchoiceState.headBlockHash` and `forkchoiceState.finalizedBlockHash` are `VALID`. The update is specified as follows:
|
||||
* The values `(forkchoiceState.headBlockHash, forkchoiceState.finalizedBlockHash)` of this method call map on the `POS_FORKCHOICE_UPDATED` event of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#block-validity) and **MUST** be processed according to the specification defined in the EIP
|
||||
* All updates to the forkchoice state resulting from this call **MUST** be made atomically.
|
||||
|
||||
1. Client software **MUST** begin a payload build process building on top of `forkchoiceState.headBlockHash` and identified via `buildProcessId` value if `payloadAttributes` is not `null` and the forkchoice state has been updated successfully. The build process is specified in the [Payload building](#payload-building) section.
|
||||
6. Client software **MUST** begin a payload build process building on top of `forkchoiceState.headBlockHash` and identified via `buildProcessId` value if `payloadAttributes` is not `null` and the forkchoice state has been updated successfully. The build process is specified in the [Payload building](#payload-building) section.
|
||||
|
||||
1. Client software **MUST** respond to this method call in the following way:
|
||||
7. Client software **MUST** respond to this method call in the following way:
|
||||
* `{payloadStatus: {status: SYNCING, latestValidHash: null, validationError: null}, payloadId: null}` if `forkchoiceState.headBlockHash` references an unknown payload or a payload that can't be validated because requisite data for the validation is missing
|
||||
* `{payloadStatus: {status: INVALID, latestValidHash: null, validationError: errorMessage | null}, payloadId: null}` obtained from the [Payload validation](#payload-validation) process if the payload is deemed `INVALID`
|
||||
* `{payloadStatus: {status: INVALID_TERMINAL_BLOCK, latestValidHash: null, validationError: errorMessage | null}, payloadId: null}` either obtained from the [Payload validation](#payload-validation) process or as a result of validating a PoW block referenced by `forkchoiceState.headBlockHash`
|
||||
* `{payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: null}` if the payload is deemed `VALID` and a build process hasn't been started
|
||||
* `{payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: buildProcessId}` if the payload is deemed `VALID` and the build process has begun.
|
||||
|
||||
1. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
|
||||
8. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
|
||||
|
||||
### engine_getPayloadV1
|
||||
|
||||
|
|
@ -307,6 +319,27 @@ The payload build process is specified as follows:
|
|||
|
||||
1. Given the `payloadId` client software **MUST** return the most recent version of the payload that is available in the corresponding build process at the time of receiving the call.
|
||||
|
||||
1. The call **MUST** return `-32001: Unknown payload` error if the build process identified by the `payloadId` does not exist.
|
||||
2. The call **MUST** return `-32001: Unknown payload` error if the build process identified by the `payloadId` does not exist.
|
||||
|
||||
1. Client software **MAY** stop the corresponding build process after serving this call.
|
||||
3. Client software **MAY** stop the corresponding build process after serving this call.
|
||||
|
||||
### engine_exchangeTransitionConfigurationV1
|
||||
|
||||
#### Request
|
||||
|
||||
* method: `engine_exchangeTransitionConfigurationV1`
|
||||
* params:
|
||||
1. `transitionConfiguration`: `Object` - instance of [`TransitionConfigurationV1`](#TransitionConfigurationV1); `terminalBlockNumber` **MUST** be set to `0`
|
||||
|
||||
#### Response
|
||||
|
||||
* result: [`TransitionConfigurationV1`](#TransitionConfigurationV1)
|
||||
* error: code and message set in case an exception happens while getting a transition configuration.
|
||||
|
||||
#### Specification
|
||||
|
||||
1. Execution Layer client software **MUST** respond with configurable setting values that are set according to the Client software configuration section of [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#client-software-configuration).
|
||||
|
||||
2. Execution Layer client software **SHOULD** surface an error to the user if local configuration settings mismatch corresponding values received in the call of this method, with exception for `terminalBlockNumber` value.
|
||||
|
||||
3. Consensus Layer client software **SHOULD** surface an error to the user if local configuration settings mismatch corresponding values obtained from the response to the call of this method.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
apis
|
||||
attributesv
|
||||
bytecode
|
||||
configurationv
|
||||
eip
|
||||
endian
|
||||
enum
|
||||
|
|
|
|||
Loading…
Reference in New Issue