Try It Now Dialog

engine_forkchoiceUpdatedV3

---

Method

• JSON-RPC method name: engine_forkchoiceUpdatedV3
• JSON-RPC version: 2.0

Parameters

Name	Type	Required	Description
Forkchoice state	object	yes
Payload attributes	object	no

Parameter schema

{
  "Forkchoice state": {
    "required": true,
    "schema": {
      "title": "Forkchoice state object V1",
      "type": "object",
      "required": [
        "headBlockHash",
        "safeBlockHash",
        "finalizedBlockHash"
      ],
      "properties": {
        "headBlockHash": {
          "title": "Head block hash",
          "type": "string",
          "pattern": "^0x[0-9a-f]{64}$"
        },
        "safeBlockHash": {
          "title": "Safe block hash",
          "type": "string",
          "pattern": "^0x[0-9a-f]{64}$"
        },
        "finalizedBlockHash": {
          "title": "Finalized block hash",
          "type": "string",
          "pattern": "^0x[0-9a-f]{64}$"
        }
      }
    }
  },
  "Payload attributes": {
    "required": false,
    "schema": {
      "title": "Payload attributes object V3",
      "type": "object",
      "required": [
        "timestamp",
        "prevRandao",
        "suggestedFeeRecipient",
        "withdrawals",
        "parentBeaconBlockRoot"
      ],
      "properties": {
        "timestamp": {
          "title": "Timestamp",
          "type": "string",
          "pattern": "^0x(0|[1-9a-f][0-9a-f]{0,15})$"
        },
        "prevRandao": {
          "title": "Previous randao value",
          "type": "string",
          "pattern": "^0x[0-9a-f]{64}$"
        },
        "suggestedFeeRecipient": {
          "title": "Suggested fee recipient",
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{40}$"
        },
        "withdrawals": {
          "title": "Withdrawals",
          "type": "array",
          "items": {
            "title": "Withdrawal object V1",
            "type": "object",
            "required": [
              "index",
              "validatorIndex",
              "address",
              "amount"
            ],
            "properties": {
              "index": {
                "title": "Withdrawal index",
                "type": "string",
                "pattern": "^0x(0|[1-9a-f][0-9a-f]{0,15})$"
              },
              "validatorIndex": {
                "title": "Validator index",
                "type": "string",
                "pattern": "^0x(0|[1-9a-f][0-9a-f]{0,15})$"
              },
              "address": {
                "title": "Withdrawal address",
                "type": "string",
                "pattern": "^0x[0-9a-fA-F]{40}$"
              },
              "amount": {
                "title": "Withdrawal amount",
                "type": "string",
                "pattern": "^0x(0|[1-9a-f][0-9a-f]{0,15})$"
              }
            }
          }
        },
        "parentBeaconBlockRoot": {
          "title": "Parent beacon block root",
          "type": "string",
          "pattern": "^0x[0-9a-f]{64}$"
        }
      }
    }
  }
}

Result

• Name: Response object
• Type: object

Result schema

{
  "title": "Forkchoice updated response",
  "type": "object",
  "required": [
    "payloadStatus"
  ],
  "properties": {
    "payloadStatus": {
      "title": "Payload status",
      "type": "object",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "title": "Payload validation status",
          "type": "string",
          "enum": [
            "VALID",
            "INVALID",
            "SYNCING"
          ],
          "description": "Set of possible values is restricted to VALID, INVALID, SYNCING"
        },
        "latestValidHash": {
          "title": "The hash of the most recent valid block",
          "type": "string",
          "pattern": "^0x[0-9a-f]{64}$"
        },
        "validationError": {
          "title": "Validation error message",
          "type": "string"
        }
      }
    },
    "payloadId": {
      "title": "Payload id",
      "type": "string",
      "pattern": "^0x[0-9a-f]{16}$"
    }
  }
}

Positional parameters

Parameter order:

1. Forkchoice state
2. Payload attributes

---

Errors

This method may return JSON-RPC standard errors (e.g. -32600, -32601, -32602, -32603) as well as application-specific errors.

TODO: Document method-specific error codes and conditions.

Named Parameters

{
  "jsonrpc": "2.0",
  "method": "engine_forkchoiceUpdatedV3",
  "params": {
    "Forkchoice state": {
      "headBlockHash": "string",
      "safeBlockHash": "string",
      "finalizedBlockHash": "string"
    },
    "Payload attributes": {
      "timestamp": "string",
      "prevRandao": "string",
      "suggestedFeeRecipient": "string",
      "withdrawals": [
        {
          "index": "string",
          "validatorIndex": "string",
          "address": "string",
          "amount": "string"
        }
      ],
      "parentBeaconBlockRoot": "string"
    }
  },
  "id": 1
}

Successful Response

{
  "jsonrpc": "2.0",
  "result": {
    "payloadStatus": {
      "status": "string",
      "latestValidHash": "string",
      "validationError": "string"
    },
    "payloadId": "string"
  },
  "id": 1
}

Positional Parameters

{
  "jsonrpc": "2.0",
  "method": "engine_forkchoiceUpdatedV3",
  "params": [
    {
      "headBlockHash": "string",
      "safeBlockHash": "string",
      "finalizedBlockHash": "string"
    },
    {
      "timestamp": "string",
      "prevRandao": "string",
      "suggestedFeeRecipient": "string",
      "withdrawals": [
        {
          "index": "string",
          "validatorIndex": "string",
          "address": "string",
          "amount": "string"
        }
      ],
      "parentBeaconBlockRoot": "string"
    }
  ],
  "id": 2
}

Successful Response

{
  "jsonrpc": "2.0",
  "result": {
    "payloadStatus": {
      "status": "string",
      "latestValidHash": "string",
      "validationError": "string"
    },
    "payloadId": "string"
  },
  "id": 2
}