> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.chainstack.com/feedback
```json
{
"path": "/reference/getdebugforkchoice",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Debug fork choice
> Retrieves all current fork choice context including justified and finalized checkpoints, and the complete fork choice tree with all nodes and their weights.
The `/eth/v1/debug/fork_choice` method is a debug API endpoint in the Ethereum Beacon Chain that retrieves the complete fork choice context, including justified and finalized checkpoints and the entire fork choice tree with all nodes and their weights. This endpoint provides deep insight into the consensus mechanism's decision-making process for determining the canonical chain.
**Get your own node endpoint today**
[Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required.
You can sign up with your GitHub, X, Google, or Microsoft account.
## Parameters
This endpoint does not require any parameters.
## Response
The response provides comprehensive fork choice data:
* `justified_checkpoint` — the current justified checkpoint containing:
* `epoch` — the epoch number of the justified checkpoint
* `root` — the block root of the justified checkpoint
* `finalized_checkpoint` — the current finalized checkpoint containing:
* `epoch` — the epoch number of the finalized checkpoint
* `root` — the block root of the finalized checkpoint
* `fork_choice_nodes` — array of all nodes in the fork choice tree, each containing:
* `slot` — the slot number of this block
* `block_root` — the merkle root of this beacon block
* `parent_root` — the merkle root of the parent beacon block
* `justified_epoch` — the justified epoch from this block's perspective
* `finalized_epoch` — the finalized epoch from this block's perspective
* `weight` — the cumulative weight/score of this block in the fork choice algorithm
* `validity` — the validity status (`valid`, `invalid`, or `optimistic`)
* `execution_block_hash` — the execution layer block hash
* `extra_data` — optional client-specific additional data
* `extra_data` — optional additional data at the response level (client-specific)
## Usage notes
The `/eth/v1/debug/fork_choice` method is an advanced debugging tool that exposes the internal state of the fork choice algorithm, which is the heart of Ethereum's consensus mechanism. This endpoint is invaluable for understanding how the beacon chain determines the canonical chain among potentially competing forks.
Key concepts for understanding the response:
* **Fork choice tree** — represents all known blocks and their relationships, forming a tree structure where each node is a block
* **Weight** — indicates the cumulative attestation support for each block; higher weight means more validators support this chain
* **Checkpoints** — justified and finalized checkpoints represent consensus milestones that cannot be reverted
* **Validity states**:
* `valid` — block has been fully validated
* `invalid` — block failed validation
* `optimistic` — block assumed valid but not yet verified by execution layer
This endpoint is particularly useful for:
* **Consensus debugging** — understanding why certain blocks are chosen as canonical
* **Network analysis** — identifying competing forks and their relative support
* **Performance monitoring** — tracking the efficiency of finalization
* **Research** — studying fork choice behavior under various network conditions
* **Validator operations** — understanding attestation targets and block production decisions
The fork choice algorithm uses the LMD-GHOST (Latest Message Driven - Greediest Heaviest Observed SubTree) protocol, which selects the chain with the most cumulative attestation weight while respecting finality rules.
This is a debug endpoint and may not be available on all beacon nodes. The data structure can be large on networks with many competing forks or during periods of network instability.
## OpenAPI
````yaml /openapi/ethereum_beacon_chain_api/debug/getDebugForkChoice.json GET /beacon/2f6d649e68c2f861fecd5b8a9e35139e/eth/v1/debug/fork_choice
openapi: 3.0.0
info:
title: Ethereum Beacon Debug Fork Choice API
version: 1.0.0
servers:
- url: https://ethereum-mainnet.core.chainstack.com
security: []
paths:
/beacon/2f6d649e68c2f861fecd5b8a9e35139e/eth/v1/debug/fork_choice:
get:
tags:
- Debug
summary: Get fork choice array
description: >-
Retrieves all current fork choice context including justified and
finalized checkpoints, and the complete fork choice tree with all nodes
and their weights.
operationId: getDebugForkChoice
responses:
'200':
description: Success - Fork choice data retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/GetForkChoiceResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
GetForkChoiceResponse:
type: object
description: Debugging context of fork choice
required:
- justified_checkpoint
- finalized_checkpoint
- fork_choice_nodes
properties:
justified_checkpoint:
$ref: '#/components/schemas/Checkpoint'
finalized_checkpoint:
$ref: '#/components/schemas/Checkpoint'
fork_choice_nodes:
type: array
description: Fork choice nodes representing the complete fork choice tree
minItems: 1
items:
$ref: '#/components/schemas/ForkChoiceNode'
extra_data:
type: object
description: >-
Optional extra data that clients may provide, which could differ
from client to client
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
example: 500
message:
type: string
example: Internal server error
stacktraces:
type: array
description: Optional stacktraces, sent when node is in debug mode
items:
type: string
Checkpoint:
type: object
description: The Checkpoint object from the CL spec
required:
- epoch
- root
properties:
epoch:
type: string
example: '1'
description: The epoch number of this checkpoint
root:
type: string
format: hex
example: '0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2'
pattern: ^0x[a-fA-F0-9]{64}$
description: The block root of this checkpoint
ForkChoiceNode:
type: object
description: Fork choice node attributes
required:
- slot
- block_root
- parent_root
- justified_epoch
- finalized_epoch
- weight
- validity
- execution_block_hash
properties:
slot:
type: string
example: '1'
description: The slot to which this block corresponds
block_root:
type: string
format: hex
example: '0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2'
pattern: ^0x[a-fA-F0-9]{64}$
description: The signing merkle root of the BeaconBlock
parent_root:
type: string
format: hex
example: '0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2'
pattern: ^0x[a-fA-F0-9]{64}$
description: The signing merkle root of the parent BeaconBlock
justified_epoch:
type: string
example: '1'
description: The justified epoch from this block's perspective
finalized_epoch:
type: string
example: '1'
description: The finalized epoch from this block's perspective
weight:
type: string
example: '1'
description: The weight/score of this block in the fork choice algorithm
validity:
type: string
enum:
- valid
- invalid
- optimistic
description: The validity status of this block
execution_block_hash:
type: string
format: hex
example: '0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2'
pattern: ^0x[a-fA-F0-9]{64}$
description: The block_hash from the execution_payload of the BeaconBlock
extra_data:
type: object
description: >-
Optional extra data that clients may provide, which could differ
from client to client
````