Overview

The consumer system will need to maintain the following modules to integrate with the Babylon chain:

• BTC light client module which maintains a BTC light client,
• BTC timestamping module which maintains BTC timestamps of epochs in the Babylon chain and headers in the consumer system,
• BTC staking module which maintains all finality providers and BTC delegations for the consumer system,
• Finality module which maintains finalisation status of blocks in the consumer system, and
• Incentive module which distributes rewards to finality providers and BTC delegation.

BTC light client module

The BTC light client module maintains a BTC light client, i.e., the canonical header chain of Bitcoin.

A consumer needs to know about different events happening on the Bitcoin chain, notably the inclusion of certain transactions. To make this possible in a secure way, the consumer needs to know the current state of the Bitcoin chain i.e., what is the canonical chain of the Bitcoin network.

Module parameters

The BTC light client module must have the following parameters.

// Params defines the parameters for the BTC light client module
message Params {
	// network is the network of the BTC light client, e.g., {mainnet, testnet, signet, regtest, simnet}
	bytes network = 1;
	// base_headers are the base headers that the BTC light client module starts from
  repeated BTCHeaderInfo base_headers = 2;
}

// BTCHeaderInfo is a structure that contains all relevant information about a
// BTC header
//  - Full header bytes
//  - Header hash for easy retrieval
//  - Height of the header in the BTC chain
//  - Total work spent on the header. This is the sum of the work corresponding
//  to the header Bits field
//    and the total work of the header.
message BTCHeaderInfo {
  bytes header = 1
      [ (gogoproto.customtype) =
            "github.com/babylonchain/babylon/types.BTCHeaderBytes" ];
  bytes hash = 2
      [ (gogoproto.customtype) =
            "github.com/babylonchain/babylon/types.BTCHeaderHashBytes" ];
  uint64 height = 3;
  bytes work = 4
      [ (gogoproto.customtype) = "cosmossdk.io/math.Uint" ];
}

Suggested KV store format

Headers. The Headers storage maintains all headers on the canonical chain of Bitcoin. The key is the header height in the BTC chain, and the value is a BTCHeaderInfo object which contains the BTC header along with some metadata.

// BTCHeaderInfo is a structure that contains all relevant information about a
// BTC header
//  - Full header bytes
//  - Header hash for easy retrieval
//  - Height of the header in the BTC chain
//  - Total work spent on the header. This is the sum of the work corresponding
//  to the header Bits field and the total work of the header.
message BTCHeaderInfo {
  bytes header = 1;
  bytes hash = 2;
  uint64 height = 3;
  bytes work = 4;
}

HashToHeight. The HashToHeight storage maintains an index in which the key is the BTC header hash, and the value is the BTC header's height.

This index enables efficient lookup of BTC headers by their hash. This is useful in many situations, notably when receiving a potential chain extension which does not point to the current BTC chain tip.

Messages and handlers