Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document optional debug_setHead parameter. #1791

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Document optional debug_setHead parameter. #1791

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
18ec454
Document optional parameter.
bgravenorst Mar 31, 2025
baff176
Add admonition.
bgravenorst Mar 31, 2025
05826d0
Address reviewer feedback.
bgravenorst Apr 1, 2025
2f40d6a
Apply suggestions from code review
bgravenorst Apr 2, 2025
f4b017e
Merge branch 'main' into DOC-1784
bgravenorst Apr 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 23 additions & 7 deletions docs/public-networks/reference/api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1435,18 +1435,34 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"debug_resyncWorldState","params"

### `debug_setHead`

Sets the current head of the local chain to the block matching the specified block number.
Sets the local chain head to the specified block. Optionally, moves the [bonsai](../../concepts/data-storage-formats.md#bonsai-tries)
world state to that block when setting the `shouldMoveWorldstate` parameter.

#### Parameters
Moving the world state allows expensive operations like [`debug_traceBlock`](#debug_traceblock)
to run on historical blocks without replaying all intermediate states. This is helpful to avoid
out of memory errors when executing RPC calls on historical states.

`blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter)
:::warning
Do not use this method when a consensus client is directing Besu, or while the node is
actively importing or proposing blocks as this will likely corrupt the database.

:::note
`pending` returns the same value as `latest`.
Additionally, if you move the chain head by a large number of blocks (for example, more than 5,000),
the RPC call might time out even though Besu continues the operation in the background.
:::

#### Parameters

- `blockNumber`: _string_ - hexadecimal or decimal integer representing a block number, or one of the
string tags `latest`, `earliest`, `pending`, `finalized`, or `safe`, as described in
[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter).

:::note
`pending` returns the same value as `latest`.
:::

- `shouldMoveWorldstate`: _boolean_ - (optional) move the [bonsai](../../concepts/data-storage-formats.md#bonsai-tries)
world state to the specified block if `true`. The default is `false`.

#### Returns

`result`: _string_ - `Success` or `error`
Expand Down
Loading