Block Header Settlement

This section of the Devnet showcases how block headers from major chains like Bitcoin and Ethereum can be mirrored into the VSL, enabling verifiable, cross-chain state proofs. It demonstrates how header data is fetched, signed, submitted as claims to the VSL, and independently verified for settlement.

The block header repository includes working services for generating, signing, verifying, and displaying Bitcoin and Ethereum block headers. These headers are then submitted to the VSL, allowing applications to build on verified blockchain state without directly interacting with Layer 1 nodes.

To get started, you’ll work with a demo that mirrors BTC and ETH headers through dedicated submitter and verifier services, a VSL integration backend, and a frontend UI for viewing verification results.

Getting started

The block header demo runs a full setup that mirrors BTC and ETH block headers to the VSL, showcasing the entire claim and settlement flow. Once launched, the frontend displays verification status and settlement outcomes for each block header.

Here’s what you’ll see in action:

• Header data fetched from Bitcoin and Ethereum RPC nodes.

• Claims generated and signed with submitter keys.

• Claims verified with verifier keys and attested through the VSL.

• A frontend dashboard that displays the status of each header claim.

The live instance of this demo is available at: https://blockheader.pi2.network/, and you can explore it directly there.

How it works

The demo consists of the following components:

• btc / eth services: Fetch latest block headers, sign them, and submit claims to the VSL.

• claim-verifier: Verifies submitted claims using a trusted public key and reports validation results.

• backend: A Go-based API layer that stores and serves verification results to the frontend.

• frontend: A Bun/Next.js app that displays the settlement flow in real time.

All services are coordinated using Docker Compose and are preconfigured with sample environment templates to help you get started quickly.

Try it yourself

To reproduce this locally, follow these step-by-step setup paths using the VSL Blockchain App repo:

• Overview & entry point: Start with the block-header example folder to understand the project structure and key components.

• Run the backend service: Follow the instructions in the backend folder to launch the service that handles claim generation and verification logic.

• Spin up the frontend: Go to the frontend folder. This is the UI you’ll see once everything is wired together. Install dependencies and start the server to view the block header settlement page.

• Blockchain-specific logic

  • For Ethereum-specific logic, check the eth folder.

  • For Bitcoin-related implementation, refer to the btc folder.

Each of these subfolders contains environment files, scripts, and configs specific to its blockchain.

Once your frontend is up and running, navigate to http://localhost:3000. You should see a UI like this:

The image above is a screenshot of the Block Header Settlement page, and here's how to navigate it:

• Ethereum/Bitcoin Tabs: Switch between claims from the Ethereum or Bitcoin networks.

• Block Number: Clickable links that direct you to a block explorer.

• Claim ID: Clicking this opens the VSL Explorer with detailed information about the claim.

• Claim: Click “View” to open a JSON view like the following:

{
"claim_type": "BlockHeader",
  "header": {
    "baseFeePerGas": "...",
    "gasUsed": "...",
    "miner": "...",
    ...
  },
  "metadata": {
    "chain_id": 1,
    "network": "Ethereum"
  }
}

• Created At: Timestamp indicating when the claim was created.

• Verification Time: How long it took to verify the block header — usually a few milliseconds.