Module alt_block

Alternative Block/Chain Ops

Alternative chains are chains that potentially have more proof-of-work than the main-chain which we are tracking to potentially re-org to.

Cuprate uses an ID system for alt-chains. When a split is made from the main-chain we generate a random ChainID and assign it to the chain:

     |
     |
     |   split
     |-------------
     |            |
     |            |
    \|/          \|/
 main-chain    ChainID(X)

In that example if we were to receive an alt-block which immediately follows the top block of ChainID(X) then that block will also be stored under ChainID(X). However, if it follows from another block from ChainID(X) we will split into a chain with a different ID:

     |
     |
     |   split
     |-------------
     |            |   split
     |            |-------------|
     |            |             |
     |            |             |
     |            |             |
    \|/          \|/           \|/
 main-chain    ChainID(X)    ChainID(Z)

As you can see if we wanted to get all the alt-blocks in ChainID(Z) that now includes some blocks from ChainID(X) as well. get_alt_chain_history_ranges covers this and is the method to get the ranges of heights needed from each ChainID to get all the alt-blocks in a given ChainID.

Although this should be kept in mind as a possibility, because Cuprate’s block downloader will only track a single chain it is unlikely that we will be tracking ChainIDs that don’t immediately connect to the main-chain.

Why not use the block’s previous field?

Although that would be easier, it makes getting a range of block extremely slow, as we have to build the weight cache to verify blocks, roughly 100,000 block headers needed, this cost is too high.

Functions

• add_alt_block
  Add a AltBlockInformation to the database.
• add_alt_transaction_blob
  Adds a VerifiedTransactionInformation from an alt-block if it is not already in the DB.
• flush_alt_blocks
  Flush all alt-block data from all the alt-block tables.
• get_alt_block
  Retrieves an AltBlockInformation from the database.
• get_alt_block_extended_header_from_height
  Retrieves the ExtendedBlockHeader of the alt-block with an exact AltBlockHeight.
• get_alt_block_hash
  Retrieves the hash of the block at the given block_height on the alt chain with the given ChainId.
• get_alt_chain_history_ranges
  Get the height history of an alt-chain in reverse chronological order.
• get_alt_transaction
  Retrieve a VerifiedTransactionInformation from the database.
• update_alt_chain_info
  Updates the AltChainInfo with information on a new alt-block.