Struct Chain

pub struct Chain { /* private fields */ }

Facade to the blockchain block processing pipeline and storage. Provides the current view of the TxHashSet according to the chain state. Also maintains locking for the pipeline to avoid conflicting processing.

Implementations

impl Chain

pub fn init( db_root: String, adapter: Arc<dyn ChainAdapter + Send + Sync>, genesis: Block, pow_verifier: fn(&BlockHeader) -> Result<(), Error>, archive_mode: bool, ) -> Result<Chain, Error>

Initializes the blockchain and returns a new Chain instance. Does a check on the current chain head to make sure it exists and creates one based on the genesis block if necessary.

pub fn header_pmmr(&self) -> Arc<RwLock<PMMRHandle<BlockHeader>>>

Return our shared header MMR handle.

pub fn txhashset(&self) -> Arc<RwLock<TxHashSet>>

Return our shared txhashset instance.

pub fn store(&self) -> Arc<ChainStore>

Shared store instance.

pub fn reset_sync_head(&self) -> Result<Tip, Error>

Reset sync_head to current header_head. We do this when we first transition to header_sync to ensure we extend the “sync” header MMR from a known consistent state and to ensure we track the header chain correctly at the fork point.

pub fn process_block( &self, b: Block, opts: Options, ) -> Result<Option<Tip>, Error>

Processes a single block, then checks for orphans, processing those as well if they’re found

pub fn process_block_header( &self, bh: &BlockHeader, opts: Options, ) -> Result<(), Error>

Process a block header received during “header first” propagation. Note: This will update header MMR and corresponding header_head if total work increases (on the header chain).

pub fn sync_block_headers( &self, headers: &[BlockHeader], opts: Options, ) -> Result<(), Error>

Attempt to add new headers to the header chain (or fork). This is only ever used during sync and is based on sync_head. We update header_head here if our total work increases.

pub fn is_orphan(&self, hash: &Hash) -> bool

Check if hash is for a known orphan.

pub fn orphans_evicted_len(&self) -> usize

Get the OrphanBlockPool accumulated evicted number of blocks

pub fn is_unspent( &self, output_ref: &OutputIdentifier, ) -> Result<CommitPos, Error>

For the given commitment find the unspent output and return the associated Return an error if the output does not exist or has been spent. This querying is done in a way that is consistent with the current chain state, specifically the current winning (valid, most work) fork.

pub fn get_unspent_output_at(&self, pos: u64) -> Result<Output, Error>

Retrieves an unspent output using its PMMR position

pub fn validate_tx(&self, tx: &Transaction) -> Result<(), Error>

Validate the tx against the current UTXO set.

pub fn verify_coinbase_maturity(&self, tx: &Transaction) -> Result<(), Error>

Verify we are not attempting to spend a coinbase output that has not yet sufficiently matured.

pub fn verify_tx_lock_height(&self, tx: &Transaction) -> Result<(), Error>

Verify that the tx has a lock_height that is less than or equal to the height of the next block.

pub fn validate(&self, fast_validation: bool) -> Result<(), Error>

Validate the current chain state.

pub fn set_txhashset_roots(&self, b: &mut Block) -> Result<(), Error>

Sets the txhashset roots on a brand new block by applying the block on the current txhashset state.

pub fn get_merkle_proof( &self, output: &OutputIdentifier, header: &BlockHeader, ) -> Result<MerkleProof, Error>

Return a Merkle proof for the given commitment from the store.

pub fn get_merkle_proof_for_pos( &self, commit: Commitment, ) -> Result<MerkleProof, Error>

Return a merkle proof valid for the current output pmmr state at the given pos

pub fn kernel_data_read(&self) -> Result<File, Error>

Provides a reading view into the current kernel state.

pub fn kernel_data_write(&self, reader: &mut dyn Read) -> Result<(), Error>

Writes kernels provided to us (via a kernel data download). Currently does not write these to disk and simply deserializes the provided data. TODO - Write this data to disk and validate the rebuilt kernel MMR.

pub fn txhashset_read(&self, h: Hash) -> Result<(u64, u64, File), Error>

Provides a reading view into the current txhashset state as well as the required indexes for a consumer to rewind to a consistent state at the provided block hash.

pub fn txhashset_archive_header(&self) -> Result<BlockHeader, Error>

To support the ability to download the txhashset from multiple peers in parallel, the peers must all agree on the exact binary representation of the txhashset. This means compacting and rewinding to the exact same header. Since compaction is a heavy operation, peers can agree to compact every 12 hours, and no longer support requesting arbitrary txhashsets. Here we return the header of the txhashset we are currently offering to peers.

pub fn rebuild_sync_mmr(&self, head: &Tip) -> Result<(), Error>

Rebuild the sync MMR based on current header_head. We rebuild the sync MMR when first entering sync mode so ensure we have an MMR we can safely rewind based on the headers received from a peer.

pub fn check_txhashset_needed( &self, caller: String, hashes: &mut Option<Vec<Hash>>, ) -> Result<bool, Error>

Check chain status whether a txhashset downloading is needed

pub fn clean_txhashset_sandbox(&self)

Clean the temporary sandbox folder

pub fn get_tmp_dir(&self) -> PathBuf

Specific tmp dir. Normally it’s ~/.epic/main/tmp for mainnet or ~/.epic/floo/tmp for floonet

pub fn get_tmpfile_pathname(&self, tmpfile_name: String) -> PathBuf

Get a tmp file path in above specific tmp dir (create tmp dir if not exist) Delete file if tmp file already exists

pub fn txhashset_write( &self, h: Hash, txhashset_data: File, status: &dyn TxHashsetWriteStatus, ) -> Result<bool, Error>

Writes a reading view on a txhashset state that’s been provided to us. If we’re willing to accept that new state, the data stream will be read as a zip file, unzipped and the resulting state files should be rewound to the provided indexes.

pub fn compact(&self) -> Result<(), Error>

Triggers chain compaction.

• compacts the txhashset based on current prune_list
• removes historical blocks and associated data from the db (unless archive mode)

pub fn get_last_n_output(&self, distance: u64) -> Vec<(Hash, OutputIdentifier)>

returns the last n nodes inserted into the output sum tree

pub fn get_last_n_rangeproof(&self, distance: u64) -> Vec<(Hash, RangeProof)>

as above, for rangeproofs

pub fn get_last_n_kernel(&self, distance: u64) -> Vec<(Hash, TxKernel)>

as above, for kernels

pub fn get_output_pos(&self, commit: &Commitment) -> Result<u64, Error>

Return Commit’s MMR position

pub fn unspent_outputs_by_pmmr_index( &self, start_index: u64, max_count: u64, max_pmmr_index: Option<u64>, ) -> Result<(u64, u64, Vec<Output>), Error>

outputs by insertion index

pub fn block_height_range_to_pmmr_indices( &self, start_block_height: u64, end_block_height: Option<u64>, ) -> Result<(u64, u64), Error>

Return unspent outputs as above, but bounded between a particular range of blocks

pub fn orphans_len(&self) -> usize

Orphans pool size

pub fn head(&self) -> Result<Tip, Error>

Tip (head) of the block chain.

pub fn tail(&self) -> Result<Tip, Error>

Tail of the block chain in this node after compact (cross-block cut-through)

pub fn header_head(&self) -> Result<Tip, Error>

pub fn head_header(&self) -> Result<BlockHeader, Error>

Block header for the chain head

pub fn get_block(&self, h: &Hash) -> Result<Block, Error>

Gets a block by hash

pub fn get_block_header(&self, h: &Hash) -> Result<BlockHeader, Error>

Gets a block header by hash

pub fn get_previous_header( &self, header: &BlockHeader, ) -> Result<BlockHeader, Error>

Get previous block header.

pub fn get_block_sums(&self, h: &Hash) -> Result<BlockSums, Error>

Get block_sums by header hash.

pub fn get_header_by_height(&self, height: u64) -> Result<BlockHeader, Error>

Gets the block header at the provided height. Note: Takes a read lock on the header_pmmr.

pub fn get_header_for_output( &self, output_ref: &OutputIdentifier, ) -> Result<BlockHeader, Error>

Gets the block header in which a given output appears in the txhashset.

pub fn get_kernel_height( &self, excess: &Commitment, min_height: Option<u64>, max_height: Option<u64>, ) -> Result<Option<(TxKernel, u64, u64)>, Error>

Gets the kernel with a given excess and the block height it is included in.

pub fn get_header_for_kernel_index( &self, kernel_mmr_index: u64, min_height: Option<u64>, max_height: Option<u64>, ) -> Result<BlockHeader, Error>

Gets the block header in which a given kernel mmr index appears in the txhashset.

pub fn is_on_current_chain(&self, header: &BlockHeader) -> Result<(), Error>

Verifies the given block header is actually on the current chain. Checks the header_by_height index to verify the header is where we say it is

pub fn get_sync_head(&self) -> Result<Tip, Error>

Get the tip of the current “sync” header chain. This may be significantly different to current header chain.

pub fn difficulty_iter(&self) -> Result<DifficultyIter<'_>, Error>

Builds an iterator on blocks starting from the current chain head and running backward. Specialized to return information pertaining to block difficulty calculation (timestamp and previous difficulties).

pub fn difficulty_iter_all(&self) -> Result<DifficultyIterAll<'_>, Error>

Builds an iterator on blocks starting from the current chain head and running backward, getting the block regardless the head’s PoWType. Specialized to return information pertaining to block difficulty calculation (timestamp and previous difficulties).

pub fn bottles_iter(&self, policy: u8) -> Result<BottleIter<'_>, Error>

Builds an iterator on blocks starting from the current chain head and running backward. Specialized to return information pertaining to block difficulty calculation (timestamp and previous difficulties).

pub fn block_exists(&self, h: Hash) -> Result<bool, Error>

Check whether we have a block without reading it