Skip to content

website: add example curl command to test Beacon API endpoint in blsync.md #31980

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

Merged
merged 1 commit into from
Jun 24, 2025
Merged

website: add example curl command to test Beacon API endpoint in blsync.md #31980

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
66 changes: 24 additions & 42 deletions docs/fundamentals/blsync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,67 +9,49 @@ description: Running geth with integrated beacon light client

## Usage

### Using Dynamic Checkpoint Fetch
### Integrated mode

This will automatically fetch the latest finalized checkpoint and launch Geth in snap sync mode with light client support (blsync).
To run blsync as part of Geth, you need to specify a public HTTP endpoint and a checkpoint:

Replace `<domain>` with your select beacon api provider from the provided list of [lightsync endpoints](https://s1na.github.io/light-sync-endpoints/). Replace `<checkpoint>` with a url from the list of maintained [checkpoint sync endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/). The following command can be used to run geth client with blsync directly.
- **Choose an Endpoint**: Select a reliable and available endpoint from the [Light Sync Endpoints](https://s1na.github.io/light-sync-endpoints/) list. These nodes are community-maintained.
- **Specify the Checkpoint**: Obtain a weak subjectivity checkpoint from a trusted node operator. The checkpoint should be less than 2 weeks old. Some light sync providers only support checkpoints from the last ~1 hour.

```terminal
export BEACON=<beacon> && \
export CHECKPOINT=<checkpoint> && \
geth --beacon.api=$BEACON --beacon.checkpoint=$(curl -s $CHECKPOINT/checkpointz/v1/status | jq -r '.data.finality.finalized.root')
geth --beacon.api=<endpoint> --beacon.checkpoint=<checkpoint>
```

#### Example
```terminal
export BEACON=https://lodestar-sepolia.chainsafe.io && \
export CHECKPOINT=https://sepolia.beaconstate.info && \
geth --sepolia --beacon.api=$BEACON --beacon.checkpoint=$(curl -s $CHECKPOINT/checkpointz/v1/status | jq -r '.data.finality.finalized.root')
```
#### Checkpoint

### Running with Manual Checkpoint Fetch
A checkpoint is the block root of the first proposed slot of a finalized beacon epoch. It can be found manually or automatically depending on your trust requirements.

To run blsync as part of Geth, you need to specify a public HTTP endpoint and a checkpoint:
##### Retrieve checkpoint automatically

- **Choose an Endpoint**: Select a reliable and available endpoint from the [Light Sync Endpoints](https://s1na.github.io/light-sync-endpoints/) list. These nodes are community-maintained.
Retrieving the checkpoint and starting Geth at the same time is done using proceedure below.

- **Specify the Checkpoint**: Obtain a weak subjectivity checkpoint from a trusted node operator. The checkpoint should be less than 2 weeks old.
Replace `<endpoint>` with the chosen *trusted* light sync provider from the list of [endpoints](https://s1na.github.io/light-sync-endpoints/). The following command will run Geth with the integrated blsync. Ensure [`jq`](https://jqlang.org/download/) is installed.

#### Checkpoint
```terminal
BEACON=<endpoint> geth --beacon.api=$BEACON --beacon.checkpoint=$(curl -s $BEACON/eth/v1/beacon/headers/finalized | jq -r ".data.root")
```

##### Manually find a checkpoint

A checkpoint is the block root of the first proposed slot of a finalized beacon epoch. In this guide we use [beaconcha.in](https://sepolia.beaconcha.in) to find a checkpoint:
A checkpoint can also be obtained manually. The easiest is to use [beaconcha.in](https://beaconcha.in) and cross check it with another provider like [beaconscan](https://beaconscan.com):

- Visit sepolia.beaconcha.in.
- Visit [beaconcha.in](https://beaconcha.in).
- Navigate to the latest finalized epoch that is ideally 1 hour old.
![Finding a suitable epoch](/images/docs/blsync1.png)
- Open the epoch details and find the first proposed slot at the end of the page.
![Finding the first slot](/images/docs/blsync2.png)
- Compare the block root for the slot against an another source. Verify they are equal.
- Copy the block root field.
![Copy the block root](/images/docs/blsync3.png)
- Fill in the argument for the `--beacon.checkpoint` flag with block root.


## Testing a Beacon API Endpoint

To verify that your Beacon API is reachable and returning valid data, you can use a simple `curl` command to request the light client bootstrap header for a given block root.

Replace `<domain>` with your Beacon API domain, and `<block_hash>` with the hex-encoded block root you want to test.

```terminal
curl -H "Accept: application/json" http://<domain>/eth/v1/beacon/light_client/bootstrap/<block_root>
```

#### Example
```terminal
curl -H "Accept: application/json" http://testing.holesky.beacon-api.nimbus.team/eth/v1/beacon/light_client/bootstrap/0x82e6ba0e288db5eb79c328fc6cb03a6aec921b00af6888bd51d6b000e68e75ac
```

The following command can be used to start Geth with blsync on the Sepolia network. Note that the checkpoint root will be outdated two weeks after the writing of this page and a recent one will have to be picked according to the guide above:

#### Example
###### Example

```terminal
./build/bin/geth --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36
geth --beacon.api=<endpoint> --beacon.checkpoint=<block root>
```

### Running `blsync` as a Standalone Tool
Expand All @@ -88,16 +70,16 @@ go build ./cmd/blsync

Blsync takes the same flags as above to configure the HTTP endpoint as well as checkpoint. It additionally needs flags to connect to the execution client. Specifically `--blsync.engine.api` to configure the Engine API url and `--blsync.jwtsecret` for the JWT authentication token.

Again to sync the Sepolia network in this mode, first run Geth:
To sync the Sepolia network in this mode, first run Geth:

```terminal
./build/bin/geth --sepolia --datadir light-sepolia-dir
geth --sepolia --datadir light-sepolia-dir
```

The logs will indicate the Engine API path which is by default `http://localhost:8551` and the path to the JWT secret created which is in this instance `./light-sepolia-dir/geth/jwtsecret`. Now blsync can be run:

```terminal
./blsync --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 --blsync.engine.api http://localhost:8551 --blsync.jwtsecret light-sepolia-dir/geth/jwtsecret
blsync --sepolia --beacon.api https://sepolia.lightclient.xyz --beacon.checkpoint 0x0014732c89a02315d2ada0ed2f63b32ecb8d08751c01bea39011b31ad9ecee36 --blsync.engine.api http://localhost:8551 --blsync.jwtsecret light-sepolia-dir/geth/jwtsecret

INFO [06-23|15:06:33.388] Loaded JWT secret file path=light-sepolia-dir/geth/jwtsecret crc32=0x5a92678
INFO [06-23|15:06:34.130] Successful NewPayload number=6,169,314 hash=d4204e..772e65 status=SYNCING
Expand Down