Nethereum.Beaconchain 7.1.0

Nethereum.Beaconchain

.NET client for the Ethereum Beacon Chain REST API, providing access to consensus-layer state, light client bootstrap, sync committee updates, and finality data.

Installation

dotnet add package Nethereum.Beaconchain

Or via Package Manager Console:

Install-Package Nethereum.Beaconchain

Key Components

Quick Start

Creating a BeaconApiClient

using Nethereum.Beaconchain;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

You can also supply your own HttpClient or IRestHttpHelper:

var httpClient = new HttpClient();
var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com", httpClient);

Getting Fork Version

Retrieve the fork data for a given state (defaults to "head"):

using Nethereum.Beaconchain;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");
var fork = await beaconClient.GetStateForkAsync();

var currentVersion = fork.Data.CurrentVersion;
var previousVersion = fork.Data.PreviousVersion;
var epoch = fork.Data.Epoch;

Fetching Blob Sidecars (EIP-4844)

using Nethereum.Beaconchain;
using Nethereum.Model;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

// Fetch blobs for a specific slot
var response = await beaconClient.GetBlobSidecarsAsync("9000000");

// Or fetch latest
var latest = await beaconClient.GetBlobSidecarsAsync("head");

// Decode blob data back to original bytes
var originalData = BlobSidecarHelper.DecodeData(response);

// Or get raw blobs + commitments + proofs
var sidecar = BlobSidecarHelper.ToBlobSidecar(response);

Getting Finality Updates

using Nethereum.Beaconchain;
using Nethereum.Beaconchain.LightClient;
using Nethereum.Hex.HexConvertors.Extensions;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

var response = await beaconClient.LightClient.GetFinalityUpdateAsync();
var finalityUpdate = LightClientResponseMapper.ToDomain(response);

var finalizedSlot = finalityUpdate.FinalizedHeader.Beacon.Slot;
var blockNumber = finalityUpdate.FinalizedHeader.Execution.BlockNumber;
var blockHash = finalityUpdate.FinalizedHeader.Execution.BlockHash.ToHex(true);

Getting Optimistic Updates

using Nethereum.Beaconchain;
using Nethereum.Beaconchain.LightClient;
using Nethereum.Hex.HexConvertors.Extensions;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

var response = await beaconClient.LightClient.GetOptimisticUpdateAsync();
var optimisticUpdate = LightClientResponseMapper.ToDomain(response);

var attestedSlot = optimisticUpdate.AttestedHeader.Beacon.Slot;
var blockNumber = optimisticUpdate.AttestedHeader.Execution.BlockNumber;
var blockHash = optimisticUpdate.AttestedHeader.Execution.BlockHash.ToHex(true);

Getting Light Client Bootstrap

Bootstrap requires a block root, typically obtained from a finality update:

using Nethereum.Beaconchain;
using Nethereum.Beaconchain.LightClient;
using Nethereum.Consensus.Ssz;
using Nethereum.Hex.HexConvertors.Extensions;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

var finalityResponse = await beaconClient.LightClient.GetFinalityUpdateAsync();
var finalityUpdate = LightClientResponseMapper.ToDomain(finalityResponse);
var blockRoot = finalityUpdate.FinalizedHeader.Beacon.HashTreeRoot();

var response = await beaconClient.LightClient.GetBootstrapAsync(blockRoot.ToHex(true));
var bootstrap = LightClientResponseMapper.ToDomain(response);

var slot = bootstrap.Header.Beacon.Slot;
var syncCommitteePubKeyCount = bootstrap.CurrentSyncCommittee.PubKeys.Count;
var branchCount = bootstrap.CurrentSyncCommitteeBranch.Count;

Getting Sync Period Updates

Fetch light client updates for one or more sync committee periods:

using Nethereum.Beaconchain;
using Nethereum.Beaconchain.LightClient;

var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

var finalityResponse = await beaconClient.LightClient.GetFinalityUpdateAsync();
var finalityUpdate = LightClientResponseMapper.ToDomain(finalityResponse);
var currentSlot = finalityUpdate.FinalizedHeader.Beacon.Slot;
var currentPeriod = currentSlot / (32 * 256);

var responses = await beaconClient.LightClient.GetUpdatesAsync(currentPeriod, 1);
var updates = LightClientResponseMapper.ToDomain(responses);

foreach (var update in updates)
{
    var attestedSlot = update.AttestedHeader?.Beacon?.Slot;
    var finalizedSlot = update.FinalizedHeader?.Beacon?.Slot;
}

Response DTO Structure

The API returns JSON responses that are deserialized into DTO classes in the Nethereum.Beaconchain.LightClient.Responses namespace. Key types:

Use LightClientResponseMapper.ToDomain() to convert any response DTO into the corresponding domain model from Nethereum.Consensus.Ssz (e.g., LightClientBootstrap, LightClientUpdate, LightClientFinalityUpdate, LightClientOptimisticUpdate).

Relationship to Other Packages

• Nethereum.Consensus.Ssz - Provides the domain model types (LightClientBootstrap, LightClientUpdate, BeaconBlockHeader, ExecutionPayloadHeader, SyncCommittee, SyncAggregate) that LightClientResponseMapper maps into. Also provides HashTreeRoot() for SSZ hash tree root computation.
• Nethereum.Consensus.LightClient - Implements the light client sync protocol (LightClientService) on top of this package. Uses ILightClientApi to fetch updates and LightClientResponseMapper to convert them for verification.
• Nethereum.Signer.Bls.Herumi - BLS signature verification used by LightClientService to validate sync committee signatures.
• Nethereum.ChainStateVerification - Uses the light client to obtain trusted headers and verify execution-layer state proofs (account balances, storage, code) against them.

Additional Resources

• Ethereum Beacon Chain API Specification
• Ethereum Light Client Specification
• Nethereum Documentation