Struct PartialChainState

pub struct PartialChainState(/* private fields */);

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.

We need to modify our current state as-we-go, but we also need to use the main traits that define a chainstate. Most cruccially, both crates don’t take a mutable reference in any method, so we need some form of interior mutability. We could just use a mutex, but this is not required and very wateful. Partial chains differ from the normal chain because they only have one owner, the worker responsible for driving this chain to it’s completion. Because of that, we can simply use a UnsafeCell and forbid shared access between threads by not implementing Clone.

Implementations

impl PartialChainState

pub fn list_blocks(&self) -> &[BlockHeader]

Returns all blocks in this partial chain

pub fn list_valid_blocks(&self) -> Vec<&BlockHeader>

Returns all block we have validated so far in this chain

pub fn has_invalid_blocks(&self) -> bool

Returns whether any block inside this interval is invalid

Trait Implementations

impl BlockchainInterface for PartialChainState

type Error = BlockchainError

fn get_params(&self) -> Params

fn acc(&self) -> Stump

fn get_height(&self) -> Result<u32, Self::Error>

Get the height of our best know chain.

fn get_block_hash(&self, height: u32) -> Result<BlockHash, BlockchainError>

Returns the block with a given height in our current tip.

fn get_best_block(&self) -> Result<(u32, BlockHash), Self::Error>

Returns the best known block

fn is_coinbase_mature( &self, height: u32, _block: BlockHash, ) -> Result<bool, Self::Error>

Checks if a coinbase is mature

fn get_validation_index(&self) -> Result<u32, Self::Error>

Returns the last block we validated

fn is_in_ibd(&self) -> bool

Tells whether or not we are on IBD

fn get_block_locator(&self) -> Result<Vec<BlockHash>, Self::Error>

Returns a block locator

fn get_block_header( &self, _height: &BlockHash, ) -> Result<BlockHeader, Self::Error>

Returns associated header for block with hash

fn get_chain_tips(&self) -> Result<Vec<BlockHash>, Self::Error>

fn validate_block( &self, _block: &Block, _proof: Proof, _inputs: HashMap<OutPoint, UtxoData>, _del_hashes: Vec<Hash>, _acc: Stump, ) -> Result<(), Self::Error>

fn get_fork_point(&self, _block: BlockHash) -> Result<BlockHash, Self::Error>

fn update_acc( &self, _acc: Stump, _block: UtreexoBlock, _height: u32, _proof: Proof, _del_hashes: Vec<Hash>, ) -> Result<Stump, Self::Error>

fn get_block_locator_for_tip( &self, _tip: BlockHash, ) -> Result<Vec<BlockHash>, BlockchainError>

Returns a block locator from a given tip

fn get_block(&self, _hash: &BlockHash) -> Result<Block, Self::Error>

Returns a block with a given hash if any.

fn get_tx(&self, _txid: &Txid) -> Result<Option<Transaction>, Self::Error>

Returns a bitcoin [Transaction] given it’s txid.

fn broadcast(&self, _tx: &Transaction) -> Result<(), Self::Error>

Broadcasts a transaction to the network.

fn subscribe(&self, _tx: Arc<dyn BlockConsumer>)

Register for receiving notifications for some event. Right now it only works for new blocks, but may work with transactions in the future too. if a module performs some heavy-lifting on the block’s data, it should pass in a vector or a channel where data can be transferred to the atual worker, otherwise chainstate will be stuck for as long as you have work to do.

fn estimate_fee(&self, _target: usize) -> Result<f64, Self::Error>

Returns fee estimation for inclusion in target blocks.

fn get_block_height( &self, _hash: &BlockHash, ) -> Result<Option<u32>, Self::Error>

Returns the height of a block, given it’s hash

fn get_unbroadcasted(&self) -> Vec<Transaction>

Returns the list of unbroadcasted transactions.

impl UpdatableChainstate for PartialChainState

fn connect_block( &self, block: &Block, proof: Proof, inputs: HashMap<OutPoint, UtxoData>, del_hashes: Vec<Hash>, ) -> Result<u32, BlockchainError>

This is one of the most important methods for a ChainState, it gets a block and some utreexo data, validates this block and connects to our chain of blocks. This function is meant to be atomic and prone of running in parallel.

fn get_root_hashes(&self) -> Vec<BitcoinNodeHash>

Returns the root hashes of our utreexo forest

fn get_acc(&self) -> Stump

Returns the current accumulator

fn flush(&self) -> Result<(), BlockchainError>

Persists our data. Should be invoked periodically.

fn toggle_ibd(&self, _is_ibd: bool)

Toggle IBD on/off

fn accept_header(&self, _header: BlockHeader) -> Result<(), BlockchainError>

Accepts a new header to our chain. This method is called before connect_block, and makes some basic checks on a header and saves it on disk. We only accept a block as valid after calling connect_block.

fn switch_chain(&self, _new_tip: BlockHash) -> Result<(), BlockchainError>

fn get_partial_chain( &self, _initial_height: u32, _final_height: u32, _acc: Stump, ) -> Result<PartialChainState, BlockchainError>

Returns a partial chainstate from a range of blocks.

fn invalidate_block(&self, _block: BlockHash) -> Result<(), BlockchainError>

Tells this blockchain to consider this block invalid, and not build on top of it

fn handle_transaction(&self) -> Result<(), BlockchainError>

Not used for now, but in a future blockchain with mempool, we can process transactions that are not in a block yet.

fn mark_chain_as_assumed( &self, _acc: Stump, _tip: BlockHash, ) -> Result<bool, BlockchainError>

Marks a chain as fully-valid

fn mark_block_as_valid(&self, _block: BlockHash) -> Result<(), BlockchainError>

Marks one block as being fully validated, this overrides a block that was explicitly marked as invalid.

impl Send for PartialChainState

We need to send PartialChainState between threads/tasks, because the worker thread, once it finishes, needs to notify the main task and pass the final partial chain.

Safety

All items inside the UnsafeCell are Send, most importantly, there are no references or smart pointers inside it, so sending shouldn’t be a problem.

impl Sync for PartialChainState