Struct grin_chain::txhashset::Extension

pub struct Extension<'a> {
    pub batch: &'a Batch<'a>,
    // some fields omitted
}

Allows the application of new blocks on top of the sum trees in a reversible manner within a unit of work provided by the extending function.

Fields

batch: &'a Batch<'a>

Batch in which the extension occurs, public so it can be used within an extending closure. Just be careful using it that way as it will get rolled back with the extension (i.e on a losing fork).

Methods

impl<'a> Extension<'a>

pub fn utxo_view(&'a self) -> UTXOView<'a>

Build a view of the current UTXO set based on the output PMMR.

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

Apply a new block to the existing state.

Applies the following -

• header
• outputs
• inputs
• kernels

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

Get the header at the specified height based on the current state of the extension. Derives the MMR pos from the height (insertion index) and retrieves the header hash. Looks the header up in the db by hash.

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

Compares the provided header to the header in the header MMR at that height. If these match we know the header is on the current chain.

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

Build a Merkle proof for the given output and the block this extension is currently referencing. Note: this relies on the MMR being stable even after pruning/compaction. We need the hash of each sibling pos from the pos up to the peak including the sibling leaf node which may have been removed.

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

Saves a snapshot of the output and rangeproof MMRs to disk. Specifically - saves a snapshot of the utxo file, tagged with the block hash as filename suffix. Needed for fast-sync (utxo file needs to be rewound before sending across).

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

Rewinds the MMRs to the provided block, rewinding to the last output pos and last kernel pos of that block.

pub fn roots(&self) -> TxHashSetRoots

Current root hashes and sums (if applicable) for the Output, range proof and kernel sum trees.

pub fn header_root(&self) -> Hash

Get the root of the current header MMR.

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

Validate the following MMR roots against the latest header applied -

• output
• rangeproof
• kernel

Note we do not validate the header MMR root here as we need to validate a header against the state of the MMR prior to applying it. Each header commits to the root of the MMR of all previous headers, not including the header itself.

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

Validate the provided header by comparing its prev_root to the root of the current header MMR.

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

Validate the header, output and kernel MMR sizes against the block header.

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

Validate full kernel sums against the provided header (for overage and kernel_offset). This is an expensive operation as we need to retrieve all the UTXOs and kernels from the respective MMRs. For a significantly faster way of validating full kernel sums see BlockSums.

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

Validate the txhashset state against the provided block header. A "fast validation" will skip rangeproof verification and kernel signature verification.

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

Rebuild the index of MMR positions to the corresponding Output and kernel by iterating over the whole MMR data. This is a costly operation performed only when we receive a full new chain state.

pub fn force_rollback(&mut self)

Force the rollback of this extension, no matter the result

pub fn dump_output_pmmr(&self)

Dumps the output MMR. We use this after compacting for visual confirmation that it worked.

pub fn dump(&self, short: bool)

Dumps the state of the 3 sum trees to stdout for debugging. Short version only prints the Output tree.

pub fn sizes(&self) -> (u64, u64, u64, u64)

Sizes of each of the sum trees

Trait Implementations

impl<'a> Committed for Extension<'a>

fn inputs_committed(&self) -> Vec<Commitment>

Vector of input commitments to verify.

fn outputs_committed(&self) -> Vec<Commitment>

Vector of output commitments to verify.

fn kernels_committed(&self) -> Vec<Commitment>

Vector of kernel excesses to verify.

fn sum_kernel_excesses(
    &self,
    offset: &BlindingFactor
) -> Result<(Commitment, Commitment), Error>

Gather the kernel excesses and sum them.

fn sum_commitments(&self, overage: i64) -> Result<Commitment, Error>

Gathers commitments and sum them.

fn verify_kernel_sums(
    &self,
    overage: i64,
    kernel_offset: BlindingFactor
) -> Result<(Commitment, Commitment), Error>

Verify the sum of the kernel excesses equals the sum of the outputs, taking into account both the kernel_offset and overage.