solana_entry/

entry.rs

//! The `entry` module is a fundamental building block of Proof of History. It contains a
//! unique ID that is the hash of the Entry before it, plus the hash of the
//! transactions within it. Entries cannot be reordered, and its field `num_hashes`
//! represents an approximate amount of time since the last Entry was created.
use {
    crate::poh::Poh,
    agave_transaction_view::{
        transaction_data::TransactionData, transaction_view::UnsanitizedTransactionView,
    },
    crossbeam_channel::{Receiver, Sender},
    log::*,
    rayon::{ThreadPool, prelude::*},
    smallvec::SmallVec,
    solana_address::Address,
    solana_cost_model::shred_limit::DEFAULT_MAX_DATA_SHREDS_PER_SLOT,
    solana_hash::Hash,
    solana_merkle_tree::MerkleTree,
    solana_runtime_transaction::transaction_with_meta::TransactionWithMeta,
    solana_signature::Signature,
    solana_transaction::{Transaction, versioned::VersionedTransaction},
    solana_transaction_error::{TransactionError, TransactionResult as Result},
    std::{fmt::Formatter, iter::repeat_with, time::Instant},
    wincode::{SchemaRead, SchemaWrite, containers::Vec as WincodeVec, len::BincodeLen},
};

pub type EntrySender = Sender<Vec<Entry>>;
pub type EntryReceiver = Receiver<Vec<Entry>>;

pub const MAX_DATA_SHREDS_SIZE: usize =
    DEFAULT_MAX_DATA_SHREDS_PER_SLOT as usize * solana_packet::PACKET_DATA_SIZE;
pub type MaxDataShredsLen = BincodeLen<MAX_DATA_SHREDS_SIZE>;

/// Each Entry contains three pieces of data. The `num_hashes` field is the number
/// of hashes performed since the previous entry.  The `hash` field is the result
/// of hashing `hash` from the previous entry `num_hashes` times.  The `transactions`
/// field points to Transactions that took place shortly before `hash` was generated.
///
/// If you multiply `num_hashes` by the amount of time it takes to generate a new hash, you
/// get a duration estimate since the last `Entry`. Since processing power increases
/// over time, one should expect the duration `num_hashes` represents to decrease proportionally.
/// An upper bound on Duration can be estimated by assuming each hash was generated by the
/// world's fastest processor at the time the entry was recorded. Or said another way, it
/// is physically not possible for a shorter duration to have occurred if one assumes the
/// hash was computed by the world's fastest processor at that time. The hash chain is both
/// a Verifiable Delay Function (VDF) and a Proof of Work (not to be confused with Proof of
/// Work consensus!)
#[derive(Debug, Default, PartialEq, Eq, Clone, SchemaWrite, SchemaRead)]
pub struct Entry {
    /// The number of hashes since the previous Entry ID.
    pub num_hashes: u64,

    /// The SHA-256 hash `num_hashes` after the previous Entry ID.
    pub hash: Hash,

    /// An ordered list of transactions that were observed before the Entry ID was
    /// generated. They may have been observed before a previous Entry ID but were
    /// pushed back into this list to ensure deterministic interpretation of the ledger.
    #[wincode(with = "WincodeVec<VersionedTransaction, MaxDataShredsLen>")]
    pub transactions: Vec<VersionedTransaction>,
}

pub struct EntryView<D: TransactionData> {
    /// The number of hashes since the previous Entry ID.
    pub num_hashes: u64,

    /// The SHA-256 hash `num_hashes` after the previous Entry ID.
    pub hash: Hash,

    /// An ordered list of transactions that were observed before the Entry ID was
    /// generated. They may have been observed before a previous Entry ID but were
    /// pushed back into this list to ensure deterministic interpretation of the ledger.
    pub transactions: Vec<UnsanitizedTransactionView<D>>,
}

// for tests only, as this is an expensive operation and not needed in production.
#[cfg(feature = "dev-context-only-utils")]
impl<D> PartialEq for EntryView<D>
where
    D: PartialEq + TransactionData,
{
    fn eq(&self, other: &Self) -> bool {
        let same_num_hashes = self.num_hashes == other.num_hashes;
        let same_hash = self.hash == other.hash;
        let same_transactions = || {
            let same_len = self.transactions.len() == other.transactions.len();

            if !same_len {
                return false;
            }

            self.transactions
                .iter()
                .zip(other.transactions.iter())
                .all(|(tx1, tx2)| tx1.data() == tx2.data())
        };

        same_num_hashes && same_hash && same_transactions()
    }
}

impl<D> std::fmt::Debug for EntryView<D>
where
    D: TransactionData,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("EntryView")
            .field("num_hashes", &self.num_hashes)
            .field("hash", &self.hash)
            .field("transactions", &self.transactions)
            .finish()
    }
}

impl<D: TransactionData> EntryView<D> {
    pub fn is_tick(&self) -> bool {
        self.transactions.is_empty()
    }
}

/// Serializes `entries` and re-parses them through [`crate::block_component_parser::parse`] to
/// get byte-backed [`EntryView`]s, reusing the same parsing path production uses rather than
/// hand-constructing transaction views.
#[cfg(feature = "dev-context-only-utils")]
pub fn entry_views_for_tests(entries: Vec<Entry>) -> Vec<EntryView<bytes::Bytes>> {
    let component = crate::block_component::BlockComponent::new_entry_batch(entries).unwrap();
    let bytes = wincode::serialize(&component).unwrap();
    let crate::block_component::ParsedBlockComponent::EntryBatch(views) =
        crate::block_component_parser::parse(bytes).unwrap()
    else {
        panic!("expected EntryBatch");
    };
    views
}

// The data needed to verify an Entry.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct EntryVerificationData {
    pub num_hashes: u64,
    pub hash: Hash,
    pub num_transactions: usize,
    pub signatures: Vec<Signature>,
}

impl From<&Entry> for EntryVerificationData {
    fn from(entry: &Entry) -> Self {
        Self {
            num_hashes: entry.num_hashes,
            hash: entry.hash,
            num_transactions: entry.transactions.len(),
            signatures: entry
                .transactions
                .iter()
                .flat_map(|tx| tx.signatures.iter().copied())
                .collect(),
        }
    }
}

impl<D: TransactionData> From<&EntryView<D>> for EntryVerificationData {
    fn from(entry: &EntryView<D>) -> Self {
        Self {
            num_hashes: entry.num_hashes,
            hash: entry.hash,
            num_transactions: entry.transactions.len(),
            signatures: entry
                .transactions
                .iter()
                .flat_map(|tx| tx.signatures().iter().copied())
                .collect(),
        }
    }
}

impl EntryVerificationData {
    pub fn verify(&self, start_hash: &Hash) -> bool {
        let ref_hash = next_hash_with_signatures(
            start_hash,
            self.num_hashes,
            self.num_transactions,
            &self.signatures,
        );
        if self.hash != ref_hash {
            warn!(
                "next_hash is invalid expected: {:?} actual: {:?}",
                self.hash, ref_hash
            );
            return false;
        }
        true
    }
}

pub fn entries_to_verification_data(entries: &[Entry]) -> Vec<EntryVerificationData> {
    entries.iter().map(Into::into).collect()
}

pub fn entry_views_to_verification_data<D: TransactionData>(
    entries: &[EntryView<D>],
) -> Vec<EntryVerificationData> {
    entries.iter().map(Into::into).collect()
}

pub struct EntrySummary {
    pub num_hashes: u64,
    pub hash: Hash,
    pub num_transactions: u64,
}

impl From<&Entry> for EntrySummary {
    fn from(entry: &Entry) -> Self {
        Self {
            num_hashes: entry.num_hashes,
            hash: entry.hash,
            num_transactions: entry.transactions.len() as u64,
        }
    }
}

impl<D: TransactionData> From<&EntryView<D>> for EntrySummary {
    fn from(entry: &EntryView<D>) -> Self {
        Self {
            num_hashes: entry.num_hashes,
            hash: entry.hash,
            num_transactions: entry.transactions.len() as u64,
        }
    }
}

/// Typed entry to distinguish between transaction and tick entries
pub enum EntryType<Tx: TransactionWithMeta> {
    Transactions(Vec<Tx>),
    Tick(Hash),
}

#[derive(Debug)]
struct TxVerificationData<D: TransactionData> {
    is_simple_vote: bool,
    signatures: SmallVec<[Signature; 2]>,
    signer_pubkeys: SmallVec<[Address; 2]>,
    message_hash: Hash,
    transaction_view: UnsanitizedTransactionView<D>,
}

pub struct UnverifiedSignatures<D: TransactionData> {
    signatures: Vec<TxVerificationData<D>>,
}

impl<D> UnverifiedSignatures<D>
where
    D: TransactionData + Send + Sync,
{
    fn with_capacity(capacity: usize) -> Self {
        Self {
            signatures: Vec::with_capacity(capacity),
        }
    }

    /// Verifies all collected signatures in parallel on the current rayon
    /// thread pool, checking each signature individually.
    pub fn verify(&self) -> Result<()> {
        let all_valid = self
            .signatures
            .par_iter()
            .flat_map_iter(|tx| {
                let message = tx.transaction_view.message_data();
                tx.signatures
                    .iter()
                    .zip(tx.signer_pubkeys.iter())
                    .map(move |(signature, pubkey)| (signature, pubkey, message))
            })
            .all(|(signature, pubkey, message)| signature.verify(pubkey.as_ref(), message));

        if all_valid {
            Ok(())
        } else {
            Err(TransactionError::SignatureFailure)
        }
    }

    #[cfg(feature = "dev-context-only-utils")]
    /// Per-signature verification baseline, kept only for benchmarking against
    /// [`Self::verify`].
    pub fn verify_single_loop_for_benches(&self) -> Result<()> {
        self.signatures.par_iter().try_for_each(|tx_signatures| {
            if tx_signatures
                .signatures
                .iter()
                .zip(tx_signatures.signer_pubkeys.iter())
                .all(|(signature, pubkey)| {
                    signature.verify(
                        pubkey.as_ref(),
                        tx_signatures.transaction_view.message_data(),
                    )
                })
            {
                Ok(())
            } else {
                Err(TransactionError::SignatureFailure)
            }
        })
    }

    pub fn len(&self) -> usize {
        self.signatures.len()
    }

    pub fn is_empty(&self) -> bool {
        self.signatures.is_empty()
    }

    pub fn verify_signatures(&self, index: usize) -> bool {
        let tx_data = &self.signatures[index];
        let message = tx_data.transaction_view.message_data();
        tx_data
            .signatures
            .iter()
            .zip(&tx_data.signer_pubkeys)
            .all(|(signature, pubkey)| signature.verify(pubkey.as_ref(), message))
    }

    pub fn vote_transaction_message_hash(&self, index: usize) -> Option<Hash> {
        let tx_data = &self.signatures[index];
        (tx_data.is_simple_vote && !tx_data.signatures.is_empty()).then_some(tx_data.message_hash)
    }

    pub fn vote_transaction_message_hashes(&self) -> Vec<Hash> {
        self.signatures
            .iter()
            .filter(|tx_signatures| tx_signatures.is_simple_vote)
            .filter_map(|tx_signatures| {
                tx_signatures
                    .signatures
                    .first()
                    .map(|_| tx_signatures.message_hash)
            })
            .collect()
    }
}

pub struct ValidatedHashedTransactions<Tx: TransactionWithMeta, D: TransactionData> {
    pub entries: Vec<EntryType<Tx>>,
    pub unverified_signatures: UnverifiedSignatures<D>,
}

impl Entry {
    /// Creates the next Entry `num_hashes` after `start_hash`.
    pub fn new(prev_hash: &Hash, mut num_hashes: u64, transactions: Vec<Transaction>) -> Self {
        // If you passed in transactions, but passed in num_hashes == 0, then
        // next_hash will generate the next hash and set num_hashes == 1
        if num_hashes == 0 && !transactions.is_empty() {
            num_hashes = 1;
        }

        let transactions = transactions.into_iter().map(Into::into).collect::<Vec<_>>();
        let hash = next_hash(prev_hash, num_hashes, &transactions);
        Entry {
            num_hashes,
            hash,
            transactions,
        }
    }

    pub fn new_mut(
        start_hash: &mut Hash,
        num_hashes: &mut u64,
        transactions: Vec<Transaction>,
    ) -> Self {
        let entry = Self::new(start_hash, *num_hashes, transactions);
        *start_hash = entry.hash;
        *num_hashes = 0;

        entry
    }

    #[cfg(test)]
    pub fn new_tick(num_hashes: u64, hash: &Hash) -> Self {
        Entry {
            num_hashes,
            hash: *hash,
            transactions: vec![],
        }
    }

    /// Verifies self.hash is the result of hashing a `start_hash` `self.num_hashes` times.
    /// If the transaction is not a Tick, then hash that as well.
    pub fn verify(&self, start_hash: &Hash) -> bool {
        EntryVerificationData::from(self).verify(start_hash)
    }

    pub fn is_tick(&self) -> bool {
        self.transactions.is_empty()
    }
}

pub fn hash_signatures(signatures: &[impl AsRef<[u8]>]) -> Hash {
    let merkle_tree = MerkleTree::new(signatures);
    if let Some(root_hash) = merkle_tree.get_root() {
        *root_hash
    } else {
        Hash::default()
    }
}

pub fn hash_transactions(transactions: &[VersionedTransaction]) -> Hash {
    // a hash of a slice of transactions only needs to hash the signatures
    let signatures: Vec<_> = transactions
        .iter()
        .flat_map(|tx| tx.signatures.iter())
        .collect();
    hash_signatures(&signatures)
}

fn next_hash_with_signatures(
    start_hash: &Hash,
    num_hashes: u64,
    num_transactions: usize,
    signatures: &[Signature],
) -> Hash {
    if num_hashes == 0 && num_transactions == 0 {
        return *start_hash;
    }

    let mut poh = Poh::new(*start_hash, None);
    poh.hash(num_hashes.saturating_sub(1));
    if num_transactions == 0 {
        poh.tick().unwrap().hash
    } else {
        poh.record(hash_signatures(signatures)).unwrap().hash
    }
}

/// Creates the hash `num_hashes` after `start_hash`. If the transaction contains a signature, the
/// final hash will be a hash of both the previous ID and the signature.  If num_hashes is zero and
/// there's no transaction data, start_hash is returned.
pub fn next_hash(
    start_hash: &Hash,
    num_hashes: u64,
    transactions: &[VersionedTransaction],
) -> Hash {
    let signatures: Vec<_> = transactions
        .iter()
        .flat_map(|tx| tx.signatures.iter().copied())
        .collect();
    next_hash_with_signatures(start_hash, num_hashes, transactions.len(), &signatures)
}

pub struct EntryVerificationState {
    verification_status: bool,
    poh_duration_us: u64,
}

impl EntryVerificationState {
    pub fn status(&self) -> bool {
        self.verification_status
    }

    pub fn poh_duration_us(&self) -> u64 {
        self.poh_duration_us
    }
}

fn validate_and_hash_entry_transactions<Tx: TransactionWithMeta, F, D>(
    entry: EntryView<D>,
    verify: &F,
    unverified_signatures: &mut UnverifiedSignatures<D>,
) -> Result<EntryType<Tx>>
where
    F: Fn(UnsanitizedTransactionView<D>) -> Result<Tx>,
    D: TransactionData + Clone,
{
    if entry.transactions.is_empty() {
        return Ok(EntryType::Tick(entry.hash));
    }

    let verified_transactions = entry
        .transactions
        .into_iter()
        .map(|transaction_view| {
            let num_signers: usize = transaction_view.num_required_signatures().into();
            let static_account_keys = transaction_view.static_account_keys();
            if static_account_keys.len() < num_signers {
                return Err(TransactionError::SanitizeFailure);
            }
            let signatures = transaction_view.signatures().iter().copied().collect();
            let signer_pubkeys = static_account_keys[..num_signers].iter().copied().collect();
            let verified_transaction = verify(transaction_view.clone())?;
            let message_hash = *verified_transaction.message_hash();
            unverified_signatures.signatures.push(TxVerificationData {
                is_simple_vote: verified_transaction.is_simple_vote_transaction(),
                signatures,
                message_hash,
                transaction_view,
                signer_pubkeys,
            });

            Ok(verified_transaction)
        })
        .collect::<Result<Vec<_>>>()?;
    Ok(EntryType::Transactions(verified_transactions))
}

/// Validates and hashes the transactions included in the given entries.
///
/// The function does NOT verify transaction signatures. The caller is expected to call
/// `UnverifiedSignatures::verify()` on the returned `unverified_signatures`.
pub fn validate_and_hash_transactions<Tx, F, D>(
    entries: Vec<EntryView<D>>,
    num_txs: usize,
    thread_pool: &ThreadPool,
    verify: F,
) -> Result<ValidatedHashedTransactions<Tx, D>>
where
    Tx: TransactionWithMeta + Send + Sync,
    F: Fn(UnsanitizedTransactionView<D>) -> Result<Tx> + Send + Sync,
    D: TransactionData + Clone + Send + Sync,
{
    const PARALLEL_VERIFY_THRESHOLD: usize = 200;
    if num_txs < PARALLEL_VERIFY_THRESHOLD {
        let mut unverified_signatures = UnverifiedSignatures::with_capacity(num_txs);
        let entries = entries
            .into_iter()
            .map(|entry| {
                validate_and_hash_entry_transactions(entry, &verify, &mut unverified_signatures)
            })
            .collect::<Result<_>>()?;
        return Ok(ValidatedHashedTransactions {
            entries,
            unverified_signatures,
        });
    }

    let verified = thread_pool.install(|| {
        entries
            .into_par_iter()
            .map(|entry| {
                let mut unverified_signatures =
                    UnverifiedSignatures::with_capacity(entry.transactions.len());
                let verified_entry = validate_and_hash_entry_transactions(
                    entry,
                    &verify,
                    &mut unverified_signatures,
                )?;
                Ok((verified_entry, unverified_signatures))
            })
            .collect::<Result<Vec<_>>>()
    })?;

    let mut entries = Vec::with_capacity(verified.len());
    let mut unverified_signatures = UnverifiedSignatures::with_capacity(num_txs);
    for (entry, mut tx_unverified_signatures) in verified {
        entries.push(entry);
        unverified_signatures
            .signatures
            .append(&mut tx_unverified_signatures.signatures);
    }
    Ok(ValidatedHashedTransactions {
        entries,
        unverified_signatures,
    })
}

pub fn verify_entries_cpu_in_pool(
    entries: &[EntryVerificationData],
    start_hash: &Hash,
    thread_pool: &ThreadPool,
) -> EntryVerificationState {
    thread_pool.install(|| verify_entries_cpu(entries, start_hash))
}

fn verify_entries_cpu_generic(
    entries: &[EntryVerificationData],
    start_hash: &Hash,
) -> EntryVerificationState {
    let now = Instant::now();
    let genesis = [EntryVerificationData {
        num_hashes: 0,
        hash: *start_hash,
        num_transactions: 0,
        signatures: Vec::new(),
    }];
    let entry_pairs = genesis.par_iter().chain(entries).zip(entries);
    let res = entry_pairs.all(|(x0, x1)| {
        let r = x1.verify(&x0.hash);
        if !r {
            warn!(
                "entry invalid!: x0: {:?}, x1: {:?} num txs: {}",
                x0.hash, x1.hash, x1.num_transactions
            );
        }
        r
    });
    let poh_duration_us = now.elapsed().as_micros() as u64;
    EntryVerificationState {
        verification_status: res,
        poh_duration_us,
    }
}

pub fn verify_entries_cpu(
    entries: &[EntryVerificationData],
    start_hash: &Hash,
) -> EntryVerificationState {
    verify_entries_cpu_generic(entries, start_hash)
}

// an EntrySlice is a slice of Entries
pub trait EntrySlice {
    /// Verifies the hashes and counts of a slice of transactions are all consistent.
    fn verify_cpu(&self, start_hash: &Hash) -> EntryVerificationState;
    fn verify_cpu_generic(&self, start_hash: &Hash) -> EntryVerificationState;
    fn verify(&self, start_hash: &Hash, thread_pool: &ThreadPool) -> EntryVerificationState;
}

impl EntrySlice for [Entry] {
    fn verify(&self, start_hash: &Hash, thread_pool: &ThreadPool) -> EntryVerificationState {
        let verification_entries = entries_to_verification_data(self);
        verify_entries_cpu_in_pool(&verification_entries, start_hash, thread_pool)
    }

    fn verify_cpu_generic(&self, start_hash: &Hash) -> EntryVerificationState {
        let verification_entries = entries_to_verification_data(self);
        verify_entries_cpu_generic(&verification_entries, start_hash)
    }

    fn verify_cpu(&self, start_hash: &Hash) -> EntryVerificationState {
        let verification_entries = entries_to_verification_data(self);
        verify_entries_cpu(&verification_entries, start_hash)
    }
}

impl EntrySliceTickCheck for [Entry] {
    fn verify_tick_hash_count(&self, tick_hash_count: &mut u64, hashes_per_tick: u64) -> bool {
        // When hashes_per_tick is 0, hashing is disabled.
        if hashes_per_tick == 0 {
            return true;
        }

        for entry in self {
            *tick_hash_count = tick_hash_count.saturating_add(entry.num_hashes);
            if entry.is_tick() {
                if entry.num_hashes == 0 {
                    return false;
                }
                if *tick_hash_count != hashes_per_tick {
                    warn!(
                        "invalid tick hash count!: entry: {entry:#?}, tick_hash_count: \
                         {tick_hash_count}, hashes_per_tick: {hashes_per_tick}"
                    );
                    return false;
                }
                *tick_hash_count = 0;
            }
        }
        *tick_hash_count < hashes_per_tick
    }

    fn tick_count(&self) -> u64 {
        self.iter().filter(|e| e.is_tick()).count() as u64
    }
}
pub trait EntrySliceTickCheck {
    /// Checks that each entry tick has the correct number of hashes. Entry slices do not
    /// necessarily end in a tick, so `tick_hash_count` is used to carry over the hash count
    /// for the next entry slice.
    fn verify_tick_hash_count(&self, tick_hash_count: &mut u64, hashes_per_tick: u64) -> bool;

    /// Counts tick entries
    fn tick_count(&self) -> u64;
}

impl<D: TransactionData> EntrySliceTickCheck for [EntryView<D>] {
    fn verify_tick_hash_count(&self, tick_hash_count: &mut u64, hashes_per_tick: u64) -> bool {
        // When hashes_per_tick is 0, hashing is disabled.
        if hashes_per_tick == 0 {
            return true;
        }

        for entry in self {
            *tick_hash_count = tick_hash_count.saturating_add(entry.num_hashes);
            if entry.is_tick() {
                if entry.num_hashes == 0 {
                    return false;
                }
                if *tick_hash_count != hashes_per_tick {
                    warn!(
                        "invalid tick hash count!: entry: {entry:#?}, tick_hash_count: \
                         {tick_hash_count}, hashes_per_tick: {hashes_per_tick}"
                    );
                    return false;
                }
                *tick_hash_count = 0;
            }
        }
        *tick_hash_count < hashes_per_tick
    }

    fn tick_count(&self) -> u64 {
        self.iter().filter(|e| e.is_tick()).count() as u64
    }
}

pub fn next_entry_mut(start: &mut Hash, num_hashes: u64, transactions: Vec<Transaction>) -> Entry {
    let entry = Entry::new(start, num_hashes, transactions);
    *start = entry.hash;
    entry
}

pub fn create_ticks(num_ticks: u64, hashes_per_tick: u64, mut hash: Hash) -> Vec<Entry> {
    repeat_with(|| next_entry_mut(&mut hash, hashes_per_tick, vec![]))
        .take(num_ticks as usize)
        .collect()
}

/// Creates the next Tick or Transaction Entry `num_hashes` after `start_hash`.
pub fn next_entry(prev_hash: &Hash, num_hashes: u64, transactions: Vec<Transaction>) -> Entry {
    let transactions = transactions.into_iter().map(Into::into).collect::<Vec<_>>();
    next_versioned_entry(prev_hash, num_hashes, transactions)
}

/// Creates the next Tick or Transaction Entry `num_hashes` after `start_hash`.
pub fn next_versioned_entry(
    prev_hash: &Hash,
    num_hashes: u64,
    transactions: Vec<VersionedTransaction>,
) -> Entry {
    assert!(num_hashes > 0 || transactions.is_empty());
    Entry {
        num_hashes,
        hash: next_hash(prev_hash, num_hashes, &transactions),
        transactions,
    }
}

pub fn thread_pool_for_tests() -> ThreadPool {
    // Allocate fewer threads for unit tests
    // Unit tests typically aren't creating massive blocks to verify, and
    // multiple tests could be running in parallel so any further parallelism
    // will do more harm than good
    rayon::ThreadPoolBuilder::new()
        .num_threads(4)
        .thread_name(|i| format!("solEntryTest{i:02}"))
        .build()
        .expect("new rayon threadpool")
}

#[cfg(feature = "dev-context-only-utils")]
pub fn thread_pool_for_benches() -> ThreadPool {
    rayon::ThreadPoolBuilder::new()
        .num_threads(num_cpus::get())
        .thread_name(|i| format!("solEntryBnch{i:02}"))
        .build()
        .expect("new rayon threadpool")
}

#[cfg(test)]
mod tests {
    use {
        super::*,
        crate::block_component::{BlockComponent, ParsedBlockComponent},
        agave_reserved_account_keys::ReservedAccountKeys,
        agave_transaction_view::transaction_view::SanitizedTransactionView,
        bytes::Bytes,
        rand::{Rng, rng},
        rayon::ThreadPoolBuilder,
        solana_hash::Hash,
        solana_keypair::Keypair,
        solana_measure::measure::Measure,
        solana_message::{
            MessageHeader, VersionedMessage, compiled_instruction::CompiledInstruction, v1,
        },
        solana_perf::test_tx::test_tx,
        solana_pubkey::Pubkey,
        solana_runtime_transaction::{
            runtime_transaction::{ReplayTransaction, RuntimeTransaction},
            sanitize_config::sanitize_config,
        },
        solana_sha256_hasher::hash,
        solana_signature::Signature,
        solana_signer::Signer,
        solana_system_transaction as system_transaction,
        solana_transaction::{sanitized::MessageHash, versioned::VersionedTransaction},
        solana_transaction_error::TransactionResult as Result,
    };

    fn entry_view_from_entry(entry: Entry) -> EntryView<Bytes> {
        let component = BlockComponent::new_entry_batch(vec![entry]).unwrap();
        let bytes = wincode::serialize(&component).unwrap();
        let ParsedBlockComponent::EntryBatch(mut views) =
            crate::block_component_parser::parse(bytes).unwrap()
        else {
            panic!("expected EntryBatch");
        };
        views.pop().unwrap()
    }

    fn simple_v1_transaction_for_deserialization_tests() -> VersionedTransaction {
        VersionedTransaction {
            signatures: vec![Signature::default()],
            message: VersionedMessage::V1(v1::Message {
                header: MessageHeader {
                    num_required_signatures: 1,
                    num_readonly_signed_accounts: 0,
                    num_readonly_unsigned_accounts: 1,
                },
                config: v1::TransactionConfig::empty(),
                lifetime_specifier: Hash::new_unique(),
                account_keys: vec![Pubkey::new_unique(), Pubkey::new_unique()],
                instructions: vec![CompiledInstruction {
                    program_id_index: 1,
                    accounts: vec![0],
                    data: vec![],
                }],
            }),
        }
    }

    fn create_random_ticks(num_ticks: u64, max_hashes_per_tick: u64, mut hash: Hash) -> Vec<Entry> {
        repeat_with(|| {
            let hashes_per_tick = rng().random_range(1..max_hashes_per_tick);
            next_entry_mut(&mut hash, hashes_per_tick, vec![])
        })
        .take(num_ticks as usize)
        .collect()
    }

    #[test]
    fn test_entry_verify() {
        let zero = Hash::default();
        let one = hash(zero.as_ref());
        assert!(Entry::new_tick(0, &zero).verify(&zero)); // base case, never used
        assert!(!Entry::new_tick(0, &zero).verify(&one)); // base case, bad
        assert!(next_entry(&zero, 1, vec![]).verify(&zero)); // inductive step
        assert!(!next_entry(&zero, 1, vec![]).verify(&one)); // inductive step, bad
    }

    fn test_verify_transactions<Tx: TransactionWithMeta + Send + Sync + 'static>(
        entries: Vec<EntryView<Bytes>>,
        skip_verification: bool,
        thread_pool: &ThreadPool,
        verify: impl Fn(UnsanitizedTransactionView<Bytes>) -> Result<Tx> + Send + Sync,
    ) -> bool {
        let num_txs = entries.iter().map(|entry| entry.transactions.len()).sum();
        let txs = validate_and_hash_transactions(entries, num_txs, thread_pool, verify);
        let Ok(txs) = txs else {
            return false;
        };
        skip_verification || txs.unverified_signatures.verify().is_ok()
    }

    #[test]
    fn test_entry_transaction_verify() {
        let zero = Hash::default();

        // First, verify entries
        let keypair = Keypair::new();
        let tx0 = system_transaction::transfer(&keypair, &keypair.pubkey(), 0, zero);
        let tx1 = system_transaction::transfer(&keypair, &keypair.pubkey(), 1, zero);
        let e0 = Entry::new(&zero, 0, vec![tx0, tx1]);
        assert!(e0.verify(&zero));
        let tx2 = system_transaction::transfer(&keypair, &keypair.pubkey(), 2, zero);
        let tx3 = system_transaction::transfer(&keypair, &keypair.pubkey(), 3, zero);
        let e1 = Entry::new(&zero, 0, vec![tx2, tx3]);
        assert!(e1.verify(&zero));

        let es = vec![entry_view_from_entry(e0), entry_view_from_entry(e1)];
        let thread_pool = ThreadPoolBuilder::new().build().unwrap();

        // Next, verify entry slice
        let verify_transaction = {
            move |unsanitized: UnsanitizedTransactionView<Bytes>| -> Result<ReplayTransaction> {
                let sanitized = unsanitized
                    .sanitize(&sanitize_config())
                    .map_err(|_| TransactionError::SanitizeFailure)?;
                let statically_loaded =
                    RuntimeTransaction::<SanitizedTransactionView<Bytes>>::try_new(
                        sanitized,
                        MessageHash::Compute,
                        None,
                    )?;
                ReplayTransaction::try_new(
                    statically_loaded,
                    None,
                    &ReservedAccountKeys::empty_key_set(),
                )
            }
        };

        assert!(test_verify_transactions(
            es,
            false,
            &thread_pool,
            verify_transaction
        ));
    }

    #[test]
    fn test_validate_and_hash_transactions_and_signatures() {
        let thread_pool = ThreadPoolBuilder::new().build().unwrap();
        let zero = Hash::default();
        let keypair = Keypair::new();
        let tx = system_transaction::transfer(&keypair, &keypair.pubkey(), 1, zero);
        let entries = vec![entry_view_from_entry(Entry::new(&zero, 0, vec![tx]))];

        let validate_and_hash_transaction =
            move |unsanitized: UnsanitizedTransactionView<Bytes>| -> Result<ReplayTransaction> {
                let sanitized = unsanitized
                    .sanitize(&sanitize_config())
                    .map_err(|_| TransactionError::SanitizeFailure)?;
                let statically_loaded =
                    RuntimeTransaction::<SanitizedTransactionView<Bytes>>::try_new(
                        sanitized,
                        MessageHash::Compute,
                        None,
                    )?;
                ReplayTransaction::try_new(
                    statically_loaded,
                    None,
                    &ReservedAccountKeys::empty_key_set(),
                )
            };
        let txs =
            validate_and_hash_transactions(entries, 1, &thread_pool, validate_and_hash_transaction)
                .expect("transaction validation and hashing must not verify signatures");
        assert_eq!(txs.entries.len(), 1);
        assert!(txs.unverified_signatures.verify().is_ok());

        let mut tx = system_transaction::transfer(&keypair, &keypair.pubkey(), 1, zero);
        tx.signatures[0] = solana_signature::Signature::default();
        let entries = vec![entry_view_from_entry(Entry::new(&zero, 0, vec![tx]))];
        let txs =
            validate_and_hash_transactions(entries, 1, &thread_pool, validate_and_hash_transaction)
                .expect("transaction validation and hashing must not verify signatures");
        assert_eq!(txs.entries.len(), 1);
        assert!(matches!(
            txs.unverified_signatures.verify(),
            Err(solana_transaction_error::TransactionError::SignatureFailure)
        ));
    }

    #[test]
    fn test_transaction_reorder_attack() {
        let zero = Hash::default();

        // First, verify entries
        let keypair = Keypair::new();
        let tx0 = system_transaction::transfer(&keypair, &keypair.pubkey(), 0, zero);
        let tx1 = system_transaction::transfer(&keypair, &keypair.pubkey(), 1, zero);
        let mut e0 = Entry::new(&zero, 0, vec![tx0.clone(), tx1.clone()]);
        assert!(e0.verify(&zero));

        // Next, swap two transactions and ensure verification fails.
        e0.transactions[0] = tx1.into(); // <-- attack
        e0.transactions[1] = tx0.into();
        assert!(!e0.verify(&zero));
    }

    #[test]
    fn test_transaction_signing() {
        let thread_pool = thread_pool_for_tests();

        use solana_signature::Signature;
        let zero = Hash::default();

        let keypair = Keypair::new();
        let tx0 = system_transaction::transfer(&keypair, &keypair.pubkey(), 0, zero);
        let tx1 = system_transaction::transfer(&keypair, &keypair.pubkey(), 1, zero);

        // Verify entry with 2 transactions
        let mut e0 = [Entry::new(&zero, 0, vec![tx0, tx1])];
        assert!(e0.verify(&zero, &thread_pool).status());

        // Clear signature of the first transaction, see that it does not verify
        let orig_sig = e0[0].transactions[0].signatures[0];
        e0[0].transactions[0].signatures[0] = Signature::default();
        assert!(!e0.verify(&zero, &thread_pool).status());

        // restore original signature
        e0[0].transactions[0].signatures[0] = orig_sig;
        assert!(e0.verify(&zero, &thread_pool).status());

        // Resize signatures and see verification fails.
        let len = e0[0].transactions[0].signatures.len();
        e0[0].transactions[0]
            .signatures
            .resize(len - 1, Signature::default());
        assert!(!e0.verify(&zero, &thread_pool).status());

        // Pass an entry with no transactions
        let e0 = [Entry::new(&zero, 0, vec![])];
        assert!(e0.verify(&zero, &thread_pool).status());
    }

    #[test]
    fn test_next_entry() {
        let zero = Hash::default();
        let tick = next_entry(&zero, 1, vec![]);
        assert_eq!(tick.num_hashes, 1);
        assert_ne!(tick.hash, zero);

        let tick = next_entry(&zero, 0, vec![]);
        assert_eq!(tick.num_hashes, 0);
        assert_eq!(tick.hash, zero);

        let keypair = Keypair::new();
        let tx0 = system_transaction::transfer(&keypair, &Pubkey::new_unique(), 42, zero);
        let entry0 = next_entry(&zero, 1, vec![tx0.clone()]);
        assert_eq!(entry0.num_hashes, 1);
        assert_eq!(entry0.hash, next_hash(&zero, 1, &[tx0.into()]));
    }

    #[test]
    #[should_panic]
    fn test_next_entry_panic() {
        let zero = Hash::default();
        let keypair = Keypair::new();
        let tx = system_transaction::transfer(&keypair, &keypair.pubkey(), 0, zero);
        next_entry(&zero, 0, vec![tx]);
    }

    #[test]
    fn test_verify_slice1() {
        agave_logger::setup();
        let thread_pool = thread_pool_for_tests();

        let zero = Hash::default();
        let one = hash(zero.as_ref());
        // base case
        assert!(vec![][..].verify(&zero, &thread_pool).status());
        // singleton case 1
        assert!(
            vec![Entry::new_tick(0, &zero)][..]
                .verify(&zero, &thread_pool)
                .status()
        );
        // singleton case 2, bad
        assert!(
            !vec![Entry::new_tick(0, &zero)][..]
                .verify(&one, &thread_pool)
                .status()
        );
        // inductive step
        assert!(
            vec![next_entry(&zero, 0, vec![]); 2][..]
                .verify(&zero, &thread_pool)
                .status()
        );

        let mut bad_ticks = vec![next_entry(&zero, 0, vec![]); 2];
        bad_ticks[1].hash = one;
        // inductive step, bad
        assert!(!bad_ticks.verify(&zero, &thread_pool).status());
    }

    #[test]
    fn test_verify_slice_with_hashes1() {
        agave_logger::setup();
        let thread_pool = thread_pool_for_tests();

        let zero = Hash::default();
        let one = hash(zero.as_ref());
        let two = hash(one.as_ref());
        // base case
        assert!(vec![][..].verify(&one, &thread_pool).status());
        // singleton case 1
        assert!(
            vec![Entry::new_tick(1, &two)][..]
                .verify(&one, &thread_pool)
                .status()
        );
        // singleton case 2, bad
        assert!(
            !vec![Entry::new_tick(1, &two)][..]
                .verify(&two, &thread_pool)
                .status()
        );

        let mut ticks = vec![next_entry(&one, 1, vec![])];
        ticks.push(next_entry(&ticks.last().unwrap().hash, 1, vec![]));
        // inductive step
        assert!(ticks.verify(&one, &thread_pool).status());

        let mut bad_ticks = vec![next_entry(&one, 1, vec![])];
        bad_ticks.push(next_entry(&bad_ticks.last().unwrap().hash, 1, vec![]));
        bad_ticks[1].hash = one;
        // inductive step, bad
        assert!(!bad_ticks.verify(&one, &thread_pool).status());
    }

    #[test]
    fn test_verify_slice_with_hashes_and_transactions() {
        agave_logger::setup();
        let thread_pool = thread_pool_for_tests();

        let zero = Hash::default();
        let one = hash(zero.as_ref());
        let two = hash(one.as_ref());
        let alice_keypair = Keypair::new();
        let bob_keypair = Keypair::new();
        let tx0 = system_transaction::transfer(&alice_keypair, &bob_keypair.pubkey(), 1, one);
        let tx1 = system_transaction::transfer(&bob_keypair, &alice_keypair.pubkey(), 1, one);
        // base case
        assert!(vec![][..].verify(&one, &thread_pool).status());
        // singleton case 1
        assert!(
            vec![next_entry(&one, 1, vec![tx0.clone()])][..]
                .verify(&one, &thread_pool)
                .status()
        );
        // singleton case 2, bad
        assert!(
            !vec![next_entry(&one, 1, vec![tx0.clone()])][..]
                .verify(&two, &thread_pool)
                .status()
        );

        let mut ticks = vec![next_entry(&one, 1, vec![tx0.clone()])];
        ticks.push(next_entry(
            &ticks.last().unwrap().hash,
            1,
            vec![tx1.clone()],
        ));

        // inductive step
        assert!(ticks.verify(&one, &thread_pool).status());

        let mut bad_ticks = vec![next_entry(&one, 1, vec![tx0])];
        bad_ticks.push(next_entry(&bad_ticks.last().unwrap().hash, 1, vec![tx1]));
        bad_ticks[1].hash = one;
        // inductive step, bad
        assert!(!bad_ticks.verify(&one, &thread_pool).status());
    }

    #[test]
    fn test_verify_tick_hash_count() {
        let hashes_per_tick = 10;
        let tx = VersionedTransaction::default();

        let no_hash_tx_entry = Entry {
            transactions: vec![tx.clone()],
            ..Entry::default()
        };
        let single_hash_tx_entry = Entry {
            transactions: vec![tx.clone()],
            num_hashes: 1,
            ..Entry::default()
        };
        let partial_tx_entry = Entry {
            num_hashes: hashes_per_tick - 1,
            transactions: vec![tx.clone()],
            ..Entry::default()
        };
        let full_tx_entry = Entry {
            num_hashes: hashes_per_tick,
            transactions: vec![tx.clone()],
            ..Entry::default()
        };
        let max_hash_tx_entry = Entry {
            transactions: vec![tx],
            num_hashes: u64::MAX,
            ..Entry::default()
        };

        let no_hash_tick_entry = Entry::new_tick(0, &Hash::default());
        let single_hash_tick_entry = Entry::new_tick(1, &Hash::default());
        let partial_tick_entry = Entry::new_tick(hashes_per_tick - 1, &Hash::default());
        let full_tick_entry = Entry::new_tick(hashes_per_tick, &Hash::default());
        let max_hash_tick_entry = Entry::new_tick(u64::MAX, &Hash::default());

        // empty batch should succeed if hashes_per_tick hasn't been reached
        let mut tick_hash_count = 0;
        let mut entries: Vec<Entry> = vec![];
        assert!(entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, 0);

        // empty batch should fail if hashes_per_tick has been reached
        tick_hash_count = hashes_per_tick;
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, hashes_per_tick);
        tick_hash_count = 0;

        // validation is disabled when hashes_per_tick == 0
        entries = vec![max_hash_tx_entry.clone()];
        assert!(entries.verify_tick_hash_count(&mut tick_hash_count, 0));
        assert_eq!(tick_hash_count, 0);

        // partial tick should fail
        entries = vec![partial_tick_entry.clone()];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, hashes_per_tick - 1);
        tick_hash_count = 0;

        // full tick entry should succeed
        entries = vec![no_hash_tx_entry, full_tick_entry.clone()];
        assert!(entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, 0);

        // oversized tick entry should fail
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick - 1));
        assert_eq!(tick_hash_count, hashes_per_tick);
        tick_hash_count = 0;

        // partial tx entry without tick entry should succeed
        entries = vec![partial_tx_entry];
        assert!(entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, hashes_per_tick - 1);
        tick_hash_count = 0;

        // no hash tick entry should fail
        entries = vec![no_hash_tick_entry.clone()];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, 0);

        // full tx entry with no hash tick entry should still fail
        entries = vec![full_tx_entry.clone(), no_hash_tick_entry];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, hashes_per_tick);
        tick_hash_count = 0;

        // full tx entry with oversized tick entry should fail
        entries = vec![full_tx_entry.clone(), single_hash_tick_entry.clone()];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, hashes_per_tick + 1);
        tick_hash_count = 0;

        // full tx entry without tick entry should fail
        entries = vec![full_tx_entry];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, hashes_per_tick);
        tick_hash_count = 0;

        // tx entry and a tick should succeed
        entries = vec![single_hash_tx_entry.clone(), partial_tick_entry];
        assert!(entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, 0);

        // many tx entries and a tick should succeed
        let tx_entries: Vec<Entry> = (0..hashes_per_tick - 1)
            .map(|_| single_hash_tx_entry.clone())
            .collect();
        entries = [tx_entries, vec![single_hash_tick_entry]].concat();
        assert!(entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, 0);

        // check overflow saturation should fail
        entries = vec![full_tick_entry.clone(), max_hash_tick_entry];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, u64::MAX);
        tick_hash_count = 0;

        // check overflow saturation should fail
        entries = vec![max_hash_tx_entry, full_tick_entry];
        assert!(!entries.verify_tick_hash_count(&mut tick_hash_count, hashes_per_tick));
        assert_eq!(tick_hash_count, u64::MAX);
    }

    #[test]
    fn test_poh_verify_fuzz() {
        agave_logger::setup();
        for _ in 0..100 {
            let mut time = Measure::start("ticks");
            let num_ticks = rng().random_range(1..100);
            info!("create {num_ticks} ticks:");
            let mut entries = create_random_ticks(num_ticks, 100, Hash::default());
            time.stop();

            let mut modified = false;
            if rng().random_ratio(1, 2) {
                modified = true;
                let modify_idx = rng().random_range(0..num_ticks) as usize;
                entries[modify_idx].hash = hash(&[1, 2, 3]);
            }

            info!("done.. {time}");
            let mut time = Measure::start("poh");
            let res = entries
                .verify(&Hash::default(), &thread_pool_for_tests())
                .status();
            assert_eq!(res, !modified);
            time.stop();
            info!("{time} {res}");
        }
    }

    #[test]
    fn test_hash_transactions() {
        let mut transactions: Vec<_> = [test_tx(), test_tx(), test_tx()]
            .into_iter()
            .map(VersionedTransaction::from)
            .collect();

        // Test different permutations of the transactions have different final hashes.
        // i.e. that **order** of transactions is included in the hash.
        let hash1 = hash_transactions(&transactions);
        transactions.swap(0, 1);
        let hash2 = hash_transactions(&transactions);
        assert_ne!(hash1, hash2);
    }

    #[test]
    fn test_deserialize_entries_rejects_txv1_unknown_config_mask_bit() {
        let tx = simple_v1_transaction_for_deserialization_tests();
        let entries = vec![next_versioned_entry(&Hash::default(), 1, vec![tx.clone()])];
        let mut serialized_entries = wincode::serialize(&entries).unwrap();

        assert!(wincode::deserialize::<Vec<Entry>>(&serialized_entries).is_ok());

        let serialized_tx = wincode::serialize(&tx).unwrap();
        let tx_offset = serialized_entries
            .windows(serialized_tx.len())
            .position(|window| window == serialized_tx)
            .expect("serialized transaction should be embedded in serialized entry");

        // txv1 begins with the version byte and the 3-byte legacy header.
        const TXV1_CONFIG_MASK_OFFSET: usize = 1 + 3;
        let mask_offset = tx_offset + TXV1_CONFIG_MASK_OFFSET;
        let mask_range = mask_offset..mask_offset + core::mem::size_of::<u32>();
        let mask = u32::from_le_bytes(serialized_entries[mask_range.clone()].try_into().unwrap());
        assert_eq!(mask, 0);

        let unknown_config_mask_bit = 1u32
            .checked_shl(v1::TransactionConfigMask::KNOWN_BITS.trailing_ones())
            .expect("txv1 config mask should have at least one unknown bit");
        assert_ne!(
            unknown_config_mask_bit & v1::TransactionConfigMask::KNOWN_BITS,
            unknown_config_mask_bit
        );
        serialized_entries[mask_range]
            .copy_from_slice(&(mask | unknown_config_mask_bit).to_le_bytes());

        assert!(matches!(
            wincode::deserialize::<Vec<Entry>>(&serialized_entries),
            Err(wincode::ReadError::InvalidValue(
                "invalid transaction config mask"
            ))
        ));
    }
}