Module floresta_chain::pruned_utreexo::partial_chain

A partial chain is a chain that only contains a subset of the blocks in the full chain. We use multiple partial chains to sync up with the full chain, and then merge them together to get the full chain. This allows us to make Initial Block Download in parallel.

We use a PartialChainState insted of the useal ChainState, mainly for performance. Because we assume that only one worker will hold a PartialChainState at a given time, we can drop all syncronization primitives and make a really performatic ChainState that will consume and validate blocks as fast as we possibly can.

This choice removes the use of costly atomic operations, but opens space for design flaws and memory unsoundness, so here are some tips about this module and how people looking for extend or use this code should proceed:

• Shared ownership is forbidden: if you have two threads or tasks owning this, you’ll have data race. If you want to hold shared ownership for this module, you need to place a PartialChainState inside an Arc<Mutex> yourself. Don’t just Arc this and expect it to work, as you are garanteed to have data races.
• The interior is toxic, so no peeking: no references, mutable or not, to any field should leak through the API, as we are not enforcing lifetime or borrowing rules at compile time.
• Sending is fine: There’s nothing in this module that makes it not sendable to between threads, as long as the origin thread gives away the ownership.

Structs

• PartialChainState
  A partial chain is a chain that only contains a subset of the blocks in the full chain. We use multiple partial chains to sync up with the full chain, and then merge them together to get the full chain. This allows us to conduct the sync in parallel. To build one, we need to know the initial height, the final height, and the block headers in between.