@headerprotocol/contracts

HeaderProtocol: On-Chain Block Header Service

---

Header Protocol is a smart contract system that allows other contracts to request and retrieve specific fields from Ethereum block headers. This is achieved in a secure, efficient, and trustless manner, enabling advanced use cases like on-chain randomness, gas price games, and historical data retrieval.

With Header Protocol, you can request both free tasks (no fees) and paid tasks (with fees to incentivize completion). Executors (off-chain agents) listen for requests, fetch the block header data from the blockchain, and provide it back to the protocol for on-chain validation.

---

Table of Contents

1. Features
2. How It Works
3. Block Header Indexes
4. Task Types
   • Free Tasks
   • Paid Tasks
5. Key Functions
6. Examples
7. Diagrams

---

Features

• Secure Access to Block Headers: Retrieve specific block header fields such as baseFeePerGas, mixHash, timestamp, miner, and more.
• Free or Paid Tasks: Choose between free tasks (emit events) and paid tasks (store fees for executor rewards).
• Long-Term Accessibility: Use the commit function to preserve block hashes beyond Ethereum’s 256-block limitation.
• Error Handling and Refunds: Built-in mechanisms to refund fees for incomplete tasks.
• Versatile Applications: Ideal for randomness, gas price prediction, analytics, and more.

---

How It Works

Header Protocol operates in three key phases:

1. Request Phase:

   • A contract requests specific block header data by calling request(blockNumber, headerIndex).
   • The task is either free or paid, depending on whether msg.value is provided.

2. Execution Phase:

   • Executors listen for BlockHeaderRequested events.
   • They fetch the block header from the Ethereum blockchain off-chain and call response(...) to provide the data.

3. Validation Phase:

   • The protocol validates the block header data on-chain using the blockhash function.
   • Upon successful validation:
     • Free tasks trigger the responseBlockHeader callback.
     • Paid tasks transfer the fee reward to the executor and trigger the callback.

---

Block Header Indexes

Index	Field Name	Type	Description
0	parentHash	bytes32	Hash of the parent block.
1	sha3Uncles	bytes32	Hash of the uncles' list.
2	miner	address	Address of the block miner.
3	stateRoot	bytes32	State root hash of the block.
4	transactionsRoot	bytes32	Root hash of the block's transactions.
5	receiptsRoot	bytes32	Root hash of the block's receipts.
_	logsBloom	bytes256	Logs bloom filter for the block (not retrievable onchain).
7	difficulty	uint256	Difficulty level of the block.
8	number	uint256	Block number.
9	gasLimit	uint256	Gas limit for the block.
10	gasUsed	uint256	Gas used by the block.
11	timestamp	uint256	Timestamp of the block.
_	extraData	bytes	Extra data field of the block (not retrievable onchain).
13	mixHash	bytes32	Mix hash used for proof-of-work.
14	nonce	uint64	Nonce used for mining the block.
15	baseFeePerGas	uint256	Base fee per gas unit for the block (EIP-1559).
16	withdrawalsRoot	bytes32	Withdrawals root for beacon chain withdrawals.
17	blobGasUsed	uint256	Blob gas used in the block.
18	excessBlobGas	uint256	Excess blob gas in the block.
19	parentBeaconBlockRoot	bytes32	Parent beacon block root hash.

---

Task Types

Free Tasks

Free tasks emit an event and do not store any fee. They rely on altruistic executors.

Requesting a Free Task:

protocol.request(blockNumber, headerIndex); // no msg.value

Paid Tasks

Paid tasks lock Ether as a reward for whoever responds first with the correct header data.

Requesting a Paid Task:

protocol.request{value: 1 ether}(blockNumber, headerIndex);

---

Key Functions

Request Header Data

function request(uint256 blockNumber, uint256 headerIndex) external payable;

Provide Response

function response(uint256 blockNumber, uint256 headerIndex, bytes calldata blockHeader, address contractAddress) external;

Commit Blockhash

function commit(uint256 blockNumber) external;

Refund Fees

function refund(uint256 blockNumber, uint256 headerIndex) external;

Get Header

function getHeader(uint256 blockNumber, uint256 headerIndex) external view returns (bytes32);

Get Hash

function getHash(uint256 blockNumber) external view returns (bytes32);

---

Examples

Full Open Example

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {IHeaderProtocol, IHeader} from "@headerprotocol/contracts/v1/interfaces/IHeaderProtocol.sol";

contract MockHeader is IHeader {
    IHeaderProtocol private protocol;

    // blockNumber => headerIndex => headerData
    mapping(uint256 => mapping(uint256 => bytes32)) public headers;

    constructor(address _protocol) {
        protocol = IHeaderProtocol(_protocol);
    }

    function mockRequest(
        uint256 blockNumber,
        uint256 headerIndex
    ) external payable {
        protocol.request(blockNumber, headerIndex);
    }

    // required implementation of IHeader
    function responseBlockHeader(
        uint256 blockNumber,
        uint256 headerIndex,
        bytes32 headerData
    ) external {
        require(msg.sender == address(protocol), "Only Header Protocol");
        headers[blockNumber][headerIndex] = headerData; // 30,000 gas limit, only save
    }
}

Full Reward Example

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {IHeaderProtocol, IHeader} from "@headerprotocol/contracts/v1/interfaces/IHeaderProtocol.sol";

contract MockHeader is IHeader {
    IHeaderProtocol private protocol;

    // blockNumber => headerIndex => headerData
    mapping(uint256 => mapping(uint256 => bytes32)) public headers;

    constructor(address _protocol) {
        protocol = IHeaderProtocol(_protocol);
    }

    function mockRequest(
        uint256 blockNumber,
        uint256 headerIndex
    ) external payable {
        protocol.request{value: msg.value}(blockNumber, headerIndex);
    }

    function mockCommit(uint256 blockNumber) external {
        protocol.commit(blockNumber);
    }

    function mockRefund(uint256 blockNumber, uint256 headerIndex) external {
        protocol.refund(blockNumber, headerIndex);
    }

    // required implementation of IHeader
    function responseBlockHeader(
        uint256 blockNumber,
        uint256 headerIndex,
        bytes32 headerData
    ) external {
        require(msg.sender == address(protocol), "Only Header Protocol");
        headers[blockNumber][headerIndex] = headerData; // 30,000 gas limit, only save
    }

    receive() external payable {} // accept refunds
}

---

Diagrams

sequenceDiagram
    participant User as Consumer Contract
    participant Protocol as Header Protocol
    participant Executor as Off-Chain Executor

    User->>Protocol: request(blockNumber, headerIndex)
    Protocol->>Executor: Emit BlockHeaderRequested Event
    Executor->>Executor: Fetch and Verify Block Header (Off-Chain)
    Executor->>Protocol: response(blockNumber, headerIndex, blockHeader, contractAddress)
    Protocol->>User: Trigger responseBlockHeader(blockNumber, headerIndex, headerData)