Light Client

dotnet add package Nethereum.Beaconchain              # Beacon API client
dotnet add package Nethereum.Consensus.LightClient     # Light client service, store, config
dotnet add package Nethereum.Signer.Bls.Herumi         # BLS12-381 signature verification (native)

using Nethereum.Beaconchain;
using Nethereum.Beaconchain.LightClient;
using Nethereum.Consensus.LightClient;
using Nethereum.Consensus.Ssz;
using Nethereum.Hex.HexConvertors.Extensions;
using Nethereum.Signer.Bls;
using Nethereum.Signer.Bls.Herumi;

// 1. Connect to a Beacon API endpoint
var beaconClient = new BeaconApiClient("https://ethereum-beacon-api.publicnode.com");

// 2. Fetch the weak subjectivity root from the latest finality update
var response = await beaconClient.LightClient.GetFinalityUpdateAsync();
var finalityUpdate = LightClientResponseMapper.ToDomain(response);
var weakSubjectivityRoot = finalityUpdate.FinalizedHeader.Beacon.HashTreeRoot();

// 3. Configure for mainnet
var config = new LightClientConfig
{
    GenesisValidatorsRoot = "0x4b363db94e286120d76eb905340fdd4e54bfe9f06bf33ff6cf5ad27f511bfe95".HexToByteArray(),
    CurrentForkVersion = "0x06000000".HexToByteArray(),
    SlotsPerEpoch = 32,
    SecondsPerSlot = 12,
    WeakSubjectivityRoot = weakSubjectivityRoot
};

// 4. Initialize BLS verification
var nativeBls = new NativeBls(new HerumiNativeBindings());
await nativeBls.InitializeAsync();

// 5. Create and initialize the light client
var store = new InMemoryLightClientStore();
var lightClient = new LightClientService(beaconClient.LightClient, nativeBls, config, store);
await lightClient.InitializeAsync();

// 6. Inspect initial state
var state = lightClient.GetState();
Console.WriteLine("Finalized slot: " + state.FinalizedSlot);
Console.WriteLine("Block number: " + state.FinalizedExecutionPayload.BlockNumber);
Console.WriteLine("Block hash: " + state.FinalizedExecutionPayload.BlockHash.ToHex(true));

var updated = await lightClient.UpdateAsync();
var state = lightClient.GetState();
Console.WriteLine("Current period: " + state.CurrentPeriod);
Console.WriteLine("Finalized slot: " + state.FinalizedSlot);

var finalityUpdated = await lightClient.UpdateFinalityAsync();
var state = lightClient.GetState();
Console.WriteLine("Finalized block: " + state.FinalizedExecutionPayload.BlockNumber);

var optimisticUpdated = await lightClient.UpdateOptimisticAsync();
var state = lightClient.GetState();
Console.WriteLine("Optimistic block: " + state.OptimisticExecutionPayload.BlockNumber);

var trustedProvider = new TrustedHeaderProvider(lightClient);

var finalizedHeader = trustedProvider.GetLatestFinalized();
Console.WriteLine("Finalized block: " + finalizedHeader.BlockNumber);
Console.WriteLine("State root: " + finalizedHeader.StateRoot.ToHex(true));

var optimisticHeader = trustedProvider.GetLatestOptimistic();
Console.WriteLine("Optimistic block: " + optimisticHeader.BlockNumber);

// Historical block hash lookup (up to 256 recent blocks)
var blockHash = trustedProvider.GetBlockHash(finalizedHeader.BlockNumber);

trustedProvider.FinalizedStalenessThreshold = TimeSpan.FromMinutes(30);
trustedProvider.OptimisticStalenessThreshold = TimeSpan.FromMinutes(5);

trustedProvider.StaleHeaderDetected += (sender, args) =>
{
    Console.WriteLine(args.HeaderType + " header is stale");
    Console.WriteLine("Age: " + args.Age.TotalMinutes + " minutes");
};

// Optionally throw instead of returning stale headers
trustedProvider.ThrowOnStaleHeader = true;
try
{
    var header = trustedProvider.GetLatestFinalized();
}
catch (StaleHeaderException ex)
{
    Console.WriteLine("Header age: " + ex.Age.TotalMinutes + " minutes");
}