cuprate_blockchain/ops/alt_block/
mod.rs

1//! Alternative Block/Chain Ops
2//!
3//! Alternative chains are chains that potentially have more proof-of-work than the main-chain
4//! which we are tracking to potentially re-org to.
5//!
6//! Cuprate uses an ID system for alt-chains. When a split is made from the main-chain we generate
7//! a random [`ChainID`](cuprate_types::ChainId) and assign it to the chain:
8//!
9//! ```text
10//!      |
11//!      |
12//!      |   split
13//!      |-------------
14//!      |            |
15//!      |            |
16//!     \|/          \|/
17//!  main-chain    ChainID(X)
18//! ```
19//!
20//! In that example if we were to receive an alt-block which immediately follows the top block of `ChainID(X)`
21//! then that block will also be stored under `ChainID(X)`. However, if it follows from another block from `ChainID(X)`
22//! we will split into a chain with a different ID:
23//!
24//! ```text
25//!      |
26//!      |
27//!      |   split
28//!      |-------------
29//!      |            |   split
30//!      |            |-------------|
31//!      |            |             |
32//!      |            |             |
33//!      |            |             |
34//!     \|/          \|/           \|/
35//!  main-chain    ChainID(X)    ChainID(Z)
36//! ```
37//!
38//! 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.
39//! [`get_alt_chain_history_ranges`] covers this and is the method to get the ranges of heights needed from each [`ChainID`](cuprate_types::ChainId)
40//! to get all the alt-blocks in a given [`ChainID`](cuprate_types::ChainId).
41//!
42//! Although this should be kept in mind as a possibility, because Cuprate's block downloader will only track a single chain it is
43//! unlikely that we will be tracking [`ChainID`](cuprate_types::ChainId)s that don't immediately connect to the main-chain.
44//!
45//! ## Why not use the block's `previous` field?
46//!
47//! Although that would be easier, it makes getting a range of block extremely slow, as we have to build the weight cache to verify
48//! blocks, roughly 100,000 block headers needed, this cost is too high.
49mod block;
50mod chain;
51mod tx;
52
53pub use block::{
54    add_alt_block, flush_alt_blocks, get_alt_block, get_alt_block_extended_header_from_height,
55    get_alt_block_hash,
56};
57pub use chain::{get_alt_chain_history_ranges, update_alt_chain_info};
58pub use tx::{add_alt_transaction_blob, get_alt_transaction};