IConfirmedBlockHeightExists

An interface to verify that a specified block has been confirmed on an external blockchain and to calculate block production rates.

Sourced from IConfirmedBlockHeightExists.sol on GitHub.

Overview

The IConfirmedBlockHeightExists interface allows smart contracts to verify that a specific block number exists and has reached the required confirmation threshold on an external blockchain. Additionally, it provides data to calculate block production rates over a specified time window, which can be useful for estimating transaction finality times or implementing time-dependent logic.

Supported Chains

Network Type	Supported Chains
Mainnet	BTC (Bitcoin), DOGE (Dogecoin), XRP (XRP Ledger)
Testnet	testBTC (Bitcoin Testnet v3), testDOGE, testXRP

Chain-Specific Confirmation Requirements

Chain	Chain ID	Required Confirmations	Timestamp Source
BTC	0	6	mediantime
DOGE	2	60	mediantime
XRP	3	3	close_time

Interface Definition

// SPDX-License-Identifier: MIT
pragma solidity >=0.7.6 <0.9;

/**
 * @custom:name IConfirmedBlockHeightExists
 * @custom:id 0x02
 * @custom:supported BTC, DOGE, XRP
 * @author Flare
 * @notice An assertion that a block with `blockNumber` is confirmed.
 * It also provides data to compute the block production rate in the given time range.
 * @custom:verification It is checked that the block with `blockNumber` is confirmed by at
 * least `numberOfConfirmations`.
 * If it is not, the request is rejected. We note a block on the tip of the chain is confirmed by 1 block.
 * Then `lowestQueryWindowBlock` is determined and its number and timestamp are extracted.
 *
 *
 * Current confirmation heights consensus:
 *
 *
 * | `Chain` | `chainId` | `numberOfConfirmations` | `timestamp ` |
 * | ------- | --------- | ----------------------- | ------------ |
 * | `BTC`   | 0         | 6                       | mediantime   |
 * | `DOGE`  | 2         | 60                      | mediantime   |
 * | `XRP`   | 3         | 3                       | close_time   |
 *
 *
 * @custom:lut `lowestQueryWindowBlockTimestamp`
 * @custom:lutlimit `0x127500`, `0x127500`, `0x127500`
 */
interface IConfirmedBlockHeightExists {
    /**
     * @notice Toplevel request
     * @param attestationType ID of the attestation type.
     * @param sourceId ID of the data source.
     * @param messageIntegrityCode `MessageIntegrityCode` that is derived from the expected response as defined.
     * @param requestBody Data defining the request. Type and interpretation is determined by the `attestationType`.
     */
    struct Request {
        bytes32 attestationType;
        bytes32 sourceId;
        bytes32 messageIntegrityCode;
        RequestBody requestBody;
    }

    /**
     * @notice Toplevel response
     * @param attestationType Extracted from the request.
     * @param sourceId Extracted from the request.
     * @param votingRound The ID of the State Connector round in which the request was considered.
     * @param lowestUsedTimestamp The lowest timestamp used to generate the response.
     * @param requestBody Extracted from the request.
     * @param responseBody Data defining the response. The verification rules for the construction of the
     * response body and the type are defined per specific `attestationType`.
     */
    struct Response {
        bytes32 attestationType;
        bytes32 sourceId;
        uint64 votingRound;
        uint64 lowestUsedTimestamp;
        RequestBody requestBody;
        ResponseBody responseBody;
    }

    /**
     * @notice Toplevel proof
     * @param merkleProof Merkle proof corresponding to the attestation response.
     * @param data Attestation response.
     */
    struct Proof {
        bytes32[] merkleProof;
        Response data;
    }

    /**
     * @notice Request body for ConfirmedBlockHeightExistsType attestation type
     * @param blockNumber The number of the block the request wants a confirmation of.
     * @param queryWindow The length of the period in which the block production rate is to be computed.
     */
    struct RequestBody {
        uint64 blockNumber;
        uint64 queryWindow;
    }

    /**
     * @notice Response body for ConfirmedBlockHeightExistsType attestation type
     * @custom:below `blockNumber`, `lowestQueryWindowBlockNumber`, `blockTimestamp`, `lowestQueryWindowBlockTimestamp`
     * can be used to compute the average block production time in the specified block range.
     * @param blockTimestamp The timestamp of the block with `blockNumber`.
     * @param numberOfConfirmations The depth at which a block is considered confirmed depending on the chain.
     * All attestation providers must agree on this number.
     * @param lowestQueryWindowBlockNumber The block number of the latest block that has a timestamp strictly smaller
     * than `blockTimestamp` - `queryWindow`.
     * @param lowestQueryWindowBlockTimestamp The timestamp of the block at height `lowestQueryWindowBlockNumber`.
     */
    struct ResponseBody {
        uint64 blockTimestamp;
        uint64 numberOfConfirmations;
        uint64 lowestQueryWindowBlockNumber;
        uint64 lowestQueryWindowBlockTimestamp;
    }
}

Structs

Request

Toplevel request structure.

Parameters

• attestationType: ID of the attestation type (0x02 for ConfirmedBlockHeightExists)
• sourceId: ID of the data source (e.g., BTC, DOGE, XRP)
• messageIntegrityCode: MessageIntegrityCode derived from the expected response
• requestBody: Data defining the request

Response

Toplevel response structure.

Parameters

• attestationType: Extracted from the request
• sourceId: Extracted from the request
• votingRound: The ID of the State Connector round in which the request was considered
• lowestUsedTimestamp: The lowest timestamp used to generate the response
• requestBody: Extracted from the request
• responseBody: Data defining the response

Proof

Toplevel proof structure for verification.

Parameters

• merkleProof: Merkle proof corresponding to the attestation response
• data: Attestation response

RequestBody

Request body specific to block height confirmation.

Parameters

• blockNumber: The number of the block to confirm
• queryWindow: Time period in seconds to calculate block production rate

ResponseBody

Response body specific to block height confirmation.

Parameters

• blockTimestamp: Timestamp of the block with blockNumber
• numberOfConfirmations: Required confirmations for the specific chain
• lowestQueryWindowBlockNumber: Block number of the latest block with timestamp < blockTimestamp - queryWindow
• lowestQueryWindowBlockTimestamp: Timestamp of the block at lowestQueryWindowBlockNumber

Implementation Notes

• Attestation ID: 0x02
• Timestamp values vary by chain (mediantime for BTC/DOGE, close_time for XRP)
• The lowestUsedTimestamp parameter uses the value of lowestQueryWindowBlockTimestamp
• The lutlimit (Lowest Used Timestamp limit) is 0x127500 (1,209,600 seconds = 14 days) for all supported chains

Calculating Block Production Rate

The response fields allow developers to calculate the average block production rate using the formula:

blocks_produced = blockNumber - lowestQueryWindowBlockNumber
time_elapsed = blockTimestamp - lowestQueryWindowBlockTimestamp
average_block_time = time_elapsed / blocks_produced

Usage Example

BlockchainMonitor.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0 <0.9.0;

import {ContractRegistry} from "@flarenetwork/flare-periphery-contracts/coston2/ContractRegistry.sol";
import {IFdcVerification} from "@flarenetwork/flare-periphery-contracts/coston2/IFdcVerification.sol";
import {IConfirmedBlockHeightExists} from "@flarenetwork/flare-periphery-contracts/coston2/IConfirmedBlockHeightExists.sol";

contract BlockchainMonitor {
    uint64 public latestAverageBlockTimeSeconds;

    event BlockTimeCalculated(
        uint64 indexed blockNumber,
        uint64 averageBlockTime
    );

    function processBlockHeightProof(
        IConfirmedBlockHeightExists.Proof calldata _proof
    ) external {
        // 1. FDC Logic: Verify the proof's authenticity with the Flare network.
        require(isProofValid(_proof), "Invalid block height proof");

        // 2. Business Logic: Execute actions based on the verified proof data.
        uint64 blockNumber = _proof.data.requestBody.blockNumber;
        uint64 blockTimestamp = _proof.data.responseBody.blockTimestamp;
        uint64 lowestNumber = _proof
            .data
            .responseBody
            .lowestQueryWindowBlockNumber;
        uint64 lowestTimestamp = _proof
            .data
            .responseBody
            .lowestQueryWindowBlockTimestamp;

        uint64 avgBlockTimeSeconds = 0;
        if (blockNumber > lowestNumber) {
            uint64 blocksProduced = blockNumber - lowestNumber;
            uint64 timeElapsed = blockTimestamp - lowestTimestamp;
            avgBlockTimeSeconds = timeElapsed / blocksProduced;
        }

        // Take action: update state and emit an event with the new data.
        latestAverageBlockTimeSeconds = avgBlockTimeSeconds;
        emit BlockTimeCalculated(blockNumber, avgBlockTimeSeconds);
    }

    function isProofValid(
        IConfirmedBlockHeightExists.Proof memory _proof
    ) public view returns (bool) {
        IFdcVerification fdcVerification = ContractRegistry
            .getFdcVerification();
        return fdcVerification.verifyConfirmedBlockHeightExists(_proof);
    }
}

Open example in Remix

Related Interfaces

• IFdcHub: Primary interface for requesting attestations
• IFdcVerification: Interface for verifying attestation proofs