channels_sv2 5.0.0

//! # SV2 Extended Channel - Mining Server Abstraction.
//!
//! This module defines the [`ExtendedChannel`] struct, which provides an abstraction of a SV2
//! extended channel as maintained by a mining pool server.
//!
//! ## Responsibilities
//!
//! `ExtendedChannel` is responsible for managing all the state associated with an SV2 extended
//! channel, including:
//!
//! - **Channel Parameters**: Holds the unique `channel_id`, `user_identity`, `extranonce_prefix`,
//!   and other parameters negotiated during channel opening.
//! - **Target Difficulty**: Manages the target difficulty (`target`) and maximum allowed target
//!   (`requested_max_target`), based on client requests and nominal hashrate.
//! - **Job Lifecycle Management**: Stores jobs received from new templates or custom job messages,
//!   including:
//!   - Future jobs (indexed by `template_id`)
//!   - Active job (currently being mined)
//!   - Past and stale jobs (for share validation over time)
//! - **Share Validation and Accounting**: Validates shares submitted by the miner, updating
//!   internal accounting and detecting duplicates or stale submissions. Determines if a share meets
//!   the channel or network target and responds accordingly.
//! - **Chain Tip Management**: Tracks the latest known chain tip (previous hash, timestamp, and
//!   target) for constructing headers and validating shares.
//! - **Version Rolling**: Honors server configuration on whether version rolling is permitted,
//!   validating submitted BIP320 header versions accordingly.
//!
//! ## Usage
//!
//! This struct is intended for use on the **pool server side** or by SV2-compliant job declaration
//! clients. It encapsulates logic for responding to SV2 messages such as `NewTemplate`,
//! `SetNewPrevHash`, `SetCustomMiningJob`, and `SubmitSharesExtended`.
//!
//! ## Notes
//!
//! - Only one active job is allowed at a time. Jobs from a previous chain tip become stale when a
//!   new chain tip is set.
//! - Share acknowledgment logic is tied to a configured batch size (e.g., every `N` valid shares).
//! - Extranonce validation supports dynamic updates of `extranonce_prefix` but enforces consistency
//!   with previously agreed parameters.

use crate::{
    chain_tip::ChainTip,
    extranonce_manager::{AllocatedExtranoncePrefix, ExtranoncePrefix},
    merkle_root::merkle_root_from_path,
    server::{
        error::ExtendedChannelError,
        jobs::{extended::ExtendedJob, factory::JobFactory, job_store::JobStore, JobOrigin},
        share_accounting::{ShareAccounting, ShareValidationError, ShareValidationResult},
    },
    target::{bytes_to_hex, hash_rate_to_target, u256_to_block_hash},
    MAX_EXTRANONCE_LEN,
};
use bitcoin::{
    blockdata::block::{Header, Version},
    hashes::sha256d::Hash,
    transaction::TxOut,
    CompactTarget, Target,
};
use mining_sv2::{SetCustomMiningJob, SubmitSharesExtended};
use std::{collections::HashMap, convert::TryInto, marker::PhantomData};
use template_distribution_sv2::{NewTemplate, SetNewPrevHash as SetNewPrevHashTdp};
use tracing::debug;

/// Mining Server abstraction of a Sv2 Extended Channel.
///
/// It keeps track of:
/// - the channel's unique `channel_id`
/// - the channel's `user_identity`
/// - the channel's unique `extranonce_prefix`
/// - the channel's rollable extranonce size
/// - the channel's requested max target (limit established by the client)
/// - the channel's current target
/// - the channel's mapping between `job_id` and target
/// - the channel's nominal hashrate
/// - the channel's [`JobStore`]
/// - the channel's [`JobFactory`]
/// - the channel's [`ShareAccounting`]
/// - the channel's expected share per minute
/// - the channel's [`JobFactory`]
/// - the channel's [`ChainTip`]
#[derive(Debug)]
pub struct ExtendedChannel<'a, J>
where
    J: JobStore<ExtendedJob<'a>>,
{
    channel_id: u32,
    user_identity: String,
    extranonce_prefix: ExtranoncePrefix,
    rollable_extranonce_size: u16,
    requested_max_target: Target,
    target: Target,
    job_id_to_target: HashMap<u32, Target>,
    nominal_hashrate: f32,
    job_store: J,
    job_factory: JobFactory,
    share_accounting: ShareAccounting,
    expected_share_per_minute: f32,
    chain_tip: Option<ChainTip>,
    phantom: PhantomData<&'a ()>,
}

impl<'a, J> ExtendedChannel<'a, J>
where
    J: JobStore<ExtendedJob<'a>>,
{
    /// Constructor of `ExtendedChannel` for a Sv2 Pool Server.
    /// Not meant for usage on a Sv2 Job Declaration Client.
    ///
    /// Initializes the extended channel state with the provided parameters, including channel
    /// identifiers, difficulty targets, share accounting, and job management.
    /// Returns an error if target/difficulty parameters are invalid or extranonce prefix
    /// requirements are not met.
    ///
    /// For non-JD jobs, `pool_tag_string` is added to the coinbase scriptSig in between `/`
    /// and `//` delimiters: `/pool_tag_string//`
    #[allow(clippy::too_many_arguments)]
    pub fn new_for_pool(
        channel_id: u32,
        user_identity: String,
        extranonce_prefix: AllocatedExtranoncePrefix,
        max_target: Target,
        nominal_hashrate: f32,
        version_rolling_allowed: bool,
        rollable_extranonce_size: u16,
        share_batch_size: usize,
        expected_share_per_minute: f32,
        job_store: J,
        pool_tag_string: String,
    ) -> Result<Self, ExtendedChannelError> {
        Self::new(
            channel_id,
            user_identity,
            extranonce_prefix.into(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            Some(pool_tag_string),
            None,
        )
    }

    /// Constructor of `ExtendedChannel` for a Sv2 Job Declaration Client.
    /// Not meant for usage on a Sv2 Pool Server.
    ///
    /// Initializes the extended channel state with the provided parameters, including channel
    /// identifiers, difficulty targets, share accounting, and job management.
    /// Returns an error if target/difficulty parameters are invalid or extranonce prefix
    /// requirements are not met.
    ///
    /// The `pool_tag_string` and `miner_tag_string` are added to the coinbase scriptSig in between
    /// `/` delimiters: `/pool_tag_string/miner_tag_string/`
    #[allow(clippy::too_many_arguments)]
    pub fn new_for_job_declaration_client(
        channel_id: u32,
        user_identity: String,
        extranonce_prefix: AllocatedExtranoncePrefix,
        max_target: Target,
        nominal_hashrate: f32,
        version_rolling_allowed: bool,
        rollable_extranonce_size: u16,
        share_batch_size: usize,
        expected_share_per_minute: f32,
        job_store: J,
        pool_tag_string: Option<String>,
        miner_tag_string: String,
    ) -> Result<Self, ExtendedChannelError> {
        Self::new(
            channel_id,
            user_identity,
            extranonce_prefix.into(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            pool_tag_string,
            Some(miner_tag_string),
        )
    }

    // private constructor
    #[allow(clippy::too_many_arguments)]
    fn new(
        channel_id: u32,
        user_identity: String,
        extranonce_prefix: ExtranoncePrefix,
        max_target: Target,
        nominal_hashrate: f32,
        version_rolling_allowed: bool,
        rollable_extranonce_size: u16,
        share_batch_size: usize,
        expected_share_per_minute: f32,
        job_store: J,
        pool_tag: Option<String>,
        miner_tag: Option<String>,
    ) -> Result<Self, ExtendedChannelError> {
        let target =
            match hash_rate_to_target(nominal_hashrate.into(), expected_share_per_minute.into()) {
                Ok(target) => target,
                Err(_) => {
                    return Err(ExtendedChannelError::InvalidNominalHashrate);
                }
            };

        // Clamp to max_target rather than error. The client declared max_target as
        // an acceptable difficulty floor, so using it when the initial target would
        // otherwise exceed it is always valid.
        let target = target.min(max_target);

        if extranonce_prefix.len() > MAX_EXTRANONCE_LEN as usize {
            return Err(ExtendedChannelError::ExtranoncePrefixTooLarge);
        }

        let script_sig_size = 5 + // BIP34
            1 + // OP_PUSHBYTES
            3 + // `/` delimiters
            pool_tag.as_ref().map_or(0, |s| s.len()) +
            miner_tag.as_ref().map_or(0, |s| s.len()) +
            1 + // OP_PUSHBYTES
            extranonce_prefix.len() +
            rollable_extranonce_size as usize;

        if script_sig_size > 100 {
            return Err(ExtendedChannelError::ScriptSigSizeTooLarge);
        }

        Ok(Self {
            channel_id,
            user_identity,
            extranonce_prefix,
            rollable_extranonce_size,
            requested_max_target: max_target,
            target,
            job_id_to_target: HashMap::new(),
            nominal_hashrate,
            job_store,
            job_factory: JobFactory::new(version_rolling_allowed, pool_tag, miner_tag),
            share_accounting: ShareAccounting::new(share_batch_size),
            expected_share_per_minute,
            chain_tip: None,
            phantom: PhantomData,
        })
    }

    /// Returns the unique channel ID for this channel.
    pub fn get_channel_id(&self) -> u32 {
        self.channel_id
    }

    /// Returns the user identity string associated with this channel.
    pub fn get_user_identity(&self) -> &String {
        &self.user_identity
    }

    /// Returns the extranonce prefix bytes for this channel.
    pub fn get_extranonce_prefix(&self) -> &[u8] {
        self.extranonce_prefix.as_bytes()
    }

    /// Returns the current chain tip, if set.
    pub fn get_chain_tip(&self) -> Option<&ChainTip> {
        self.chain_tip.as_ref()
    }

    /// Returns the expected number of shares per minute configured for this channel.
    pub fn get_shares_per_minute(&self) -> f32 {
        self.expected_share_per_minute
    }

    /// Only for testing purposes, not meant to be used in real apps.
    #[cfg(test)]
    fn set_chain_tip(&mut self, chain_tip: ChainTip) {
        self.chain_tip = Some(chain_tip);
    }

    /// Updates the extranonce prefix for this channel.
    ///
    /// After this call, all newly created jobs will reference the new prefix.
    /// Jobs created before the update will continue to use the previous prefix,
    /// and share validation will be performed accordingly.
    ///
    /// Returns an error if the new extranonce prefix is too large.
    pub fn set_extranonce_prefix(
        &mut self,
        extranonce_prefix: AllocatedExtranoncePrefix,
    ) -> Result<(), ExtendedChannelError> {
        if extranonce_prefix.len() > MAX_EXTRANONCE_LEN as usize {
            return Err(ExtendedChannelError::ExtranoncePrefixTooLarge);
        }

        self.extranonce_prefix = extranonce_prefix.into();

        Ok(())
    }

    /// Returns the number of bytes available for the rollable portion of the extranonce.
    pub fn get_rollable_extranonce_size(&self) -> u16 {
        self.rollable_extranonce_size
    }

    /// Returns the full extranonce size in bytes.
    pub fn get_full_extranonce_size(&self) -> usize {
        self.extranonce_prefix.len() + self.rollable_extranonce_size as usize
    }

    /// Returns the requested maximum target for this channel.
    pub fn get_requested_max_target(&self) -> &Target {
        &self.requested_max_target
    }

    /// Returns the current target for this channel.
    ///
    /// Please note that this is the current target for the channel. Jobs created before the current target was set are associated with previously set targets, for which shares will be validated against.
    pub fn get_target(&self) -> &Target {
        &self.target
    }

    /// Updates the current target for this channel.
    ///
    /// Please note that this will NOT update the target associated with jobs that were already created.
    pub fn set_target(&mut self, target: Target) {
        self.target = target;
    }

    /// Returns the job ID for a future job from a template ID, if any.
    pub fn get_future_job_id_from_template_id(&self, template_id: u64) -> Option<u32> {
        self.job_store
            .get_future_job_id_from_template_id(template_id)
    }

    /// Returns the nominal hashrate for this channel.
    pub fn get_nominal_hashrate(&self) -> f32 {
        self.nominal_hashrate
    }

    /// Updates the nominal hashrate for this channel.
    pub fn set_nominal_hashrate(&mut self, hashrate: f32) {
        self.nominal_hashrate = hashrate;
    }

    /// Updates channel configuration with a new nominal hashrate.
    ///
    /// Recomputes target difficulty and updates channel state.
    ///
    /// If the recomputed target is easier than the effective `requested_max_target`,
    /// the target is clamped to `requested_max_target`.
    ///
    /// Returns [`ExtendedChannelError::InvalidNominalHashrate`] when
    /// `new_nominal_hashrate` cannot be converted into a valid target.
    ///
    /// This can be used in two scenarios:
    /// - Client sent `UpdateChannel` message, which contains a `requested_max_target` parameter
    ///   that's also used as input.
    /// - vardiff algorithm estimated a new nominal hashrate, in which case `requested_max_target`
    ///   is `None` and we use the value from the channel state (that was set either during channel
    ///   opening or some previous `UpdateChannel` message).
    pub fn update_channel(
        &mut self,
        new_nominal_hashrate: f32,
        requested_max_target: Option<Target>,
    ) -> Result<(), ExtendedChannelError> {
        let target = match hash_rate_to_target(
            new_nominal_hashrate.into(),
            self.expected_share_per_minute.into(),
        ) {
            Ok(target) => target,
            Err(_) => {
                return Err(ExtendedChannelError::InvalidNominalHashrate);
            }
        };

        let requested_max_target = match requested_max_target {
            Some(ref requested_max_target) => requested_max_target,
            None => &self.requested_max_target,
        };

        // debug hex of target_u256 and max_Target
        // just like in share validation
        // big-endian for display
        let target_bytes = target.to_be_bytes();
        let max_target = requested_max_target;
        let max_target_bytes = max_target.to_be_bytes();

        // Get the old target for comparison on the debug log
        // Not really needed for the actual method functionality
        // But it's useful to have for debugging purposes
        let old_target = self.target;
        let old_target_bytes = old_target.to_be_bytes();

        debug!(
            "updating channel target \nold target:\t{}\nnew target:\t{}\nmax_target:\t{}",
            bytes_to_hex(&old_target_bytes),
            bytes_to_hex(&target_bytes),
            bytes_to_hex(&max_target_bytes)
        );

        // Clamp to max_target rather than error. The client declared max_target as
        // an acceptable difficulty floor, so using it when vardiff would otherwise
        // exceed it is always valid.
        let new_target = target.min(*requested_max_target);

        self.nominal_hashrate = new_nominal_hashrate;
        self.target = new_target;
        self.requested_max_target = *requested_max_target;

        Ok(())
    }

    /// Returns an owned copy of the currently active job, if any.
    pub fn get_active_job(&self) -> Option<ExtendedJob<'a>> {
        // cloning happens inside the job store
        self.job_store.get_active_job()
    }

    /// Returns an owned copy of a future job from its job ID, if any.
    pub fn get_future_job(&self, job_id: u32) -> Option<ExtendedJob<'a>> {
        // cloning happens inside the job store
        self.job_store.get_future_job(job_id)
    }

    /// Returns an owned copy of a past job from its job ID, if any.
    pub fn get_past_job(&self, job_id: u32) -> Option<ExtendedJob<'a>> {
        // cloning happens inside the job store
        self.job_store.get_past_job(job_id)
    }
    /// Returns a reference to the share accounting state for this channel.
    pub fn get_share_accounting(&self) -> &ShareAccounting {
        &self.share_accounting
    }

    /// Updates the channel state with a new template.
    ///
    /// If the template is a future template, the chain tip is not used.
    /// If the template is not a future template, the chain tip must be set.
    ///
    /// Only meant for usage on a Sv2 Pool Server or a Sv2 Job Declaration Client,
    /// but not on mining clients such as Mining Devices or Proxies.
    ///
    /// Only meant to be used if REQUIRES_CUSTOM_WORK is NOT set on the connection this channel exists on.
    /// If this flag is set, on_set_custom_mining_job should be used instead.
    pub fn on_new_template(
        &mut self,
        template: NewTemplate<'a>,
        coinbase_reward_outputs: Vec<TxOut>,
    ) -> Result<(), ExtendedChannelError> {
        match template.future_template {
            true => {
                let new_job = self
                    .job_factory
                    .new_extended_job(
                        self.channel_id,
                        None,
                        self.extranonce_prefix.as_bytes().to_vec(),
                        template.clone(),
                        coinbase_reward_outputs,
                        self.get_full_extranonce_size(),
                    )
                    .map_err(ExtendedChannelError::JobFactoryError)?;
                self.job_store.add_future_job(template.template_id, new_job);
            }
            false => {
                match self.chain_tip.clone() {
                    // we can only create non-future jobs if we have a chain tip
                    None => return Err(ExtendedChannelError::ChainTipNotSet),
                    Some(chain_tip) => {
                        let new_job = self
                            .job_factory
                            .new_extended_job(
                                self.channel_id,
                                Some(chain_tip),
                                self.extranonce_prefix.as_bytes().to_vec(),
                                template.clone(),
                                coinbase_reward_outputs,
                                self.get_full_extranonce_size(),
                            )
                            .map_err(ExtendedChannelError::JobFactoryError)?;

                        // associate the new active job with the current target
                        self.job_id_to_target
                            .insert(new_job.get_job_id(), self.target);

                        // add the new active job to the job store
                        self.job_store.add_active_job(new_job);
                    }
                }
            }
        }

        Ok(())
    }

    /// Used as an alternative to `on_new_template` when an extended job is meant to be broadcast to the group channel,
    /// instead of multiple extended jobs to different extended channels.
    ///
    /// We use this method to update the channel state, so it can validate shares from the job that was broadcast to the group channel.
    ///
    /// Only meant to be used if REQUIRES_CUSTOM_WORK is NOT set on the connection this channel exists on.
    /// If this flag is set, on_set_custom_mining_job should be used instead.
    pub fn on_group_channel_job(
        &mut self,
        mut extended_job: ExtendedJob<'a>,
    ) -> Result<(), ExtendedChannelError> {
        // make sure the extranonce prefix is associated to the channel's extranonce prefix
        extended_job.set_extranonce_prefix(self.extranonce_prefix.as_bytes().to_vec());

        let template_id = match extended_job.get_origin() {
            JobOrigin::NewTemplate(template) => template.template_id,
            JobOrigin::SetCustomMiningJob(_) => {
                return Err(ExtendedChannelError::InvalidJobOrigin);
            }
        };

        match extended_job.is_future() {
            true => {
                self.job_store.add_future_job(template_id, extended_job);
            }
            false => {
                self.job_id_to_target
                    .insert(extended_job.get_job_id(), self.target);
                self.job_store.add_active_job(extended_job);
            }
        }

        Ok(())
    }

    /// Updates the channel state with a new `SetNewPrevHash` message (Template Distribution
    /// Protocol variant).
    ///
    /// If there are future jobs in the Job Store, it activates the future job matching the
    /// `template_id` and sets it as the active job.
    ///
    /// If there are future jobs in the Job Store, but the template id is not found, returns an
    /// error.
    ///
    /// All past jobs are cleared.
    pub fn on_set_new_prev_hash(
        &mut self,
        set_new_prev_hash: SetNewPrevHashTdp<'a>,
    ) -> Result<(), ExtendedChannelError> {
        // clear the job id to target mapping
        self.job_id_to_target.clear();

        // extended channels dedicated to custom work don't need to keep track of future jobs
        match self.job_store.has_future_jobs() {
            false => {
                // explicitly mark past jobs as stale, because we're not going to
                // do it implicitly via activate_future_job in case this extended channel is doing custom work
                self.job_store.mark_past_jobs_as_stale();
            }
            true => {
                // try to activate the future job, and also mark past jobs as stale
                if !self.job_store.activate_future_job(
                    set_new_prev_hash.template_id,
                    set_new_prev_hash.header_timestamp,
                ) {
                    return Err(ExtendedChannelError::TemplateIdNotFound);
                }

                // associate the new active job with the current target
                let job_id = self
                    .job_store
                    .get_active_job()
                    .expect("active job must exist")
                    .get_job_id();
                self.job_id_to_target.insert(job_id, self.target);
            }
        }

        // clear seen shares, as shares for past chain tip will be rejected as stale
        self.share_accounting.flush_seen_shares();

        // update the chain tip
        self.chain_tip = Some(set_new_prev_hash.into());

        Ok(())
    }

    /// Updates the channel state with a new custom mining job.
    ///
    /// If there is an active job, it is moved to the past jobs.
    /// The new custom mining job is then set as the active job.
    ///
    /// Assumes SetCustomMiningJob.{prev_hash, nbits, min_ntime} have already been validated.
    /// Updates the channel's `ChainTip``.
    ///
    /// Returns the job id of the new custom mining job.
    ///
    /// To be used by a Sv2 Pool Server upon receiving a `SetCustomMiningJob` message.
    pub fn on_set_custom_mining_job(
        &mut self,
        set_custom_mining_job: SetCustomMiningJob<'a>,
    ) -> Result<u32, ExtendedChannelError> {
        let new_job = self
            .job_factory
            .new_extended_job_from_custom_job(
                set_custom_mining_job.clone(),
                self.extranonce_prefix.as_bytes().to_vec(),
                self.get_full_extranonce_size(),
            )
            .map_err(ExtendedChannelError::JobFactoryError)?;

        let job_id = new_job.get_job_id();

        self.job_store.add_active_job(new_job);

        // update the chain tip
        let set_custom_mining_job_static = set_custom_mining_job.into_static();
        let prev_hash = set_custom_mining_job_static.prev_hash;
        let nbits = set_custom_mining_job_static.nbits;
        let min_ntime = set_custom_mining_job_static.min_ntime;
        let new_chain_tip = ChainTip::new(prev_hash, nbits, min_ntime);
        self.chain_tip = Some(new_chain_tip);

        // associate the new active job with the current target
        self.job_id_to_target.insert(job_id, self.target);

        Ok(job_id)
    }

    /// Validates a share.
    ///
    /// Updates the channel state with the result of the share validation.
    pub fn validate_share(
        &mut self,
        share: SubmitSharesExtended,
    ) -> Result<ShareValidationResult, ShareValidationError> {
        let job_id = share.job_id;

        // check if job_id is active job
        let is_active_job = self
            .job_store
            .get_active_job()
            .is_some_and(|job| job.get_job_id() == job_id);

        // check if job_id is past job
        let is_past_job = self.job_store.get_past_job(job_id).is_some();

        // check if job_id is stale job
        let is_stale_job = self.job_store.get_stale_job(job_id).is_some();

        if is_stale_job {
            return Err(ShareValidationError::Stale);
        }

        // if job_id is not active, past or stale, return error
        if !is_active_job && !is_past_job && !is_stale_job {
            return Err(ShareValidationError::InvalidJobId);
        };

        let job = if is_active_job {
            self.job_store
                .get_active_job()
                .expect("active job must exist")
        } else if is_past_job {
            self.job_store
                .get_past_job(job_id)
                .expect("past job must exist")
        } else {
            self.job_store
                .get_stale_job(job_id)
                .expect("stale job must exist")
        };

        let job_target = self
            .job_id_to_target
            .get(&job_id)
            .expect("job target must exist");

        let extranonce_size = share.extranonce.inner_as_ref().len();
        if extranonce_size != self.rollable_extranonce_size as usize {
            return Err(ShareValidationError::BadExtranonceSize);
        }

        let extranonce_prefix = job.get_extranonce_prefix();
        let mut full_extranonce = vec![];
        full_extranonce.extend(extranonce_prefix.clone());
        full_extranonce.extend(share.extranonce.inner_as_ref());

        // calculate the merkle root from:
        // - job coinbase_tx_prefix
        // - full extranonce
        // - job coinbase_tx_suffix
        // - job merkle_path
        let merkle_root: [u8; 32] = merkle_root_from_path(
            &job.get_coinbase_tx_prefix_without_bip141(),
            &job.get_coinbase_tx_suffix_without_bip141(),
            full_extranonce.as_ref(),
            &job.get_merkle_path().inner_as_ref(),
        )
        .ok_or(ShareValidationError::Invalid)?
        .try_into()
        .expect("merkle root must be 32 bytes");

        let chain_tip = self
            .chain_tip
            .as_ref()
            .ok_or(ShareValidationError::NoChainTip)?;

        let prev_hash = chain_tip.prev_hash();
        let nbits = CompactTarget::from_consensus(chain_tip.nbits());

        // validate when version rolling is not allowed
        if !job.version_rolling_allowed() {
            // If version rolling is not allowed, ensure bits 13-28 are 0
            // This is done by checking if the version & 0x1fffe000 == 0
            // ref: https://github.com/bitcoin/bips/blob/master/bip-0320.mediawiki
            if (share.version & 0x1fffe000) != 0 {
                return Err(ShareValidationError::VersionRollingNotAllowed);
            }
        }

        // create the header for validation
        let header = Header {
            version: Version::from_consensus(share.version as i32),
            prev_blockhash: u256_to_block_hash(prev_hash.clone()),
            merkle_root: (*Hash::from_bytes_ref(&merkle_root)).into(),
            time: share.ntime,
            bits: nbits,
            nonce: share.nonce,
        };

        // convert the header hash to a target type for easy comparison
        let share_hash = header.block_hash();
        let raw_share_hash: [u8; 32] = *share_hash.to_raw_hash().as_ref();
        let share_hash_target = Target::from_le_bytes(raw_share_hash);
        let share_hash_as_diff = share_hash_target.difficulty_float();

        let network_target = Target::from_compact(nbits);

        // print hash_as_target and self.target as human readable hex
        let share_hash_target_bytes = share_hash_target.to_be_bytes();
        let job_target_bytes = job_target.to_be_bytes();

        debug!(
            "share validation \nshare:\t\t{}\njob target:\t{}\nnetwork target:\t{}",
            bytes_to_hex(&share_hash_target_bytes),
            bytes_to_hex(&job_target_bytes),
            format!("{:x}", network_target)
        );

        // check if a block was found
        if network_target.is_met_by(share_hash) {
            if self
                .share_accounting
                .is_share_seen(share_hash.to_raw_hash())
            {
                return Err(ShareValidationError::DuplicateShare);
            }
            self.share_accounting.update_share_accounting(
                job_target.difficulty_float(),
                share.sequence_number,
                share_hash.to_raw_hash(),
            );
            self.share_accounting.increment_blocks_found();
            self.share_accounting.mark_batch_acknowledged();

            let mut coinbase = vec![];
            coinbase.extend(job.get_coinbase_tx_prefix_with_bip141());
            coinbase.extend(full_extranonce.clone());
            coinbase.extend(job.get_coinbase_tx_suffix_with_bip141());

            match job.get_origin() {
                JobOrigin::NewTemplate(template) => {
                    let template_id = template.template_id;
                    return Ok(ShareValidationResult::BlockFound(
                        share_hash.to_raw_hash(),
                        Some(template_id),
                        coinbase,
                    ));
                }
                JobOrigin::SetCustomMiningJob(_set_custom_mining_job) => {
                    return Ok(ShareValidationResult::BlockFound(
                        share_hash.to_raw_hash(),
                        None,
                        coinbase,
                    ));
                }
            }
        }

        // check if the share hash meets the job target
        if share_hash_target <= *job_target {
            if self
                .share_accounting
                .is_share_seen(share_hash.to_raw_hash())
            {
                return Err(ShareValidationError::DuplicateShare);
            }

            self.share_accounting.update_share_accounting(
                job_target.difficulty_float(),
                share.sequence_number,
                share_hash.to_raw_hash(),
            );

            // update the best diff
            self.share_accounting.update_best_diff(share_hash_as_diff);

            Ok(ShareValidationResult::Valid(share_hash.to_raw_hash()))
        } else {
            Err(ShareValidationError::DoesNotMeetTarget)
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::{
        chain_tip::ChainTip,
        extranonce_manager::{AllocatedExtranoncePrefix, ExtranoncePrefix, ExtranoncePrefixError},
        server::{
            error::ExtendedChannelError,
            extended::ExtendedChannel,
            jobs::{
                extended::ExtendedJob,
                job_store::{DefaultJobStore, JobStore},
            },
            share_accounting::{ShareValidationError, ShareValidationResult},
        },
    };
    use binary_sv2::{Sv2Option, U256};
    use bitcoin::{transaction::TxOut, Amount, ScriptBuf, Target};
    use mining_sv2::{NewExtendedMiningJob, SetCustomMiningJob, SubmitSharesExtended};
    use std::convert::TryInto;
    use template_distribution_sv2::{NewTemplate, SetNewPrevHash};

    const SATS_AVAILABLE_IN_TEMPLATE: u64 = 5000000000;

    #[test]
    fn test_future_job_activation_flow() {
        // note:
        // the messages on this test were collected from a sane message flow
        // we use them as test vectors to assert correct behavior of job creation
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
            0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        let template = NewTemplate {
            template_id: 1,
            future_template: true,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        // match the original script format used to generate the coinbase_reward_outputs for the
        // expected job
        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0]; // SegWit version 0
        script_bytes.push(20); // Push 20 bytes (length of pubkey hash)
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        assert!(!channel.job_store.has_future_jobs());
        channel
            .on_new_template(template.clone(), coinbase_reward_outputs)
            .unwrap();
        assert!(channel.get_active_job().is_none());

        let future_job_id = channel
            .get_future_job_id_from_template_id(template.template_id)
            .unwrap();

        let future_job = channel.get_future_job(future_job_id).unwrap();

        // we know that the provided template + coinbase_reward_outputs should generate this future
        // job
        let expected_job = NewExtendedMiningJob {
            channel_id: 1,
            job_id: 1,
            min_ntime: Sv2Option::new(None),
            version: 536870912,
            version_rolling_allowed: true,
            coinbase_tx_prefix: vec![
                2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255, 38, 82, 0, 3, 47, 47, 47, 31,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_suffix: vec![
                255, 255, 255, 255, 2, 0, 242, 5, 42, 1, 0, 0, 0, 22, 0, 20, 235, 225, 183, 220,
                194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194, 8, 252, 0, 0, 0,
                0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209, 222,
                253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180, 139,
                235, 216, 54, 151, 78, 140, 249, 0, 0, 0, 0,
            ]
            .try_into()
            .unwrap(),
            merkle_path: vec![].try_into().unwrap(),
        };

        assert_eq!(future_job.get_job_message(), &expected_job);

        let ntime = 1746839905;
        let set_new_prev_hash = SetNewPrevHash {
            template_id: 1,
            prev_hash: [
                200, 53, 253, 129, 214, 31, 43, 84, 179, 58, 58, 76, 128, 213, 24, 53, 38, 144,
                205, 88, 172, 20, 251, 22, 217, 141, 21, 221, 21, 0, 0, 0,
            ]
            .into(),
            header_timestamp: ntime,
            n_bits: 503543726,
            target: [
                0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                174, 119, 3, 0, 0,
            ]
            .into(),
        };

        channel.on_set_new_prev_hash(set_new_prev_hash).unwrap();

        // we just activated the only future job
        assert!(!channel.job_store.has_future_jobs());

        let mut previously_future_job = future_job.clone();
        previously_future_job.activate(ntime);

        let activated_job = channel.get_active_job().unwrap();

        // assert that the activated job is the same as the previously future job
        assert_eq!(
            activated_job.get_job_message(),
            previously_future_job.get_job_message()
        );
    }

    #[test]
    fn test_non_future_job_creation_flow() {
        // note:
        // the messages on this test were collected from a sane message flow
        // we use them as test vectors to assert correct behavior of job creation

        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
            0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        let ntime = 1746839905;
        let prev_hash = [
            200, 53, 253, 129, 214, 31, 43, 84, 179, 58, 58, 76, 128, 213, 24, 53, 38, 144, 205,
            88, 172, 20, 251, 22, 217, 141, 21, 221, 21, 0, 0, 0,
        ]
        .into();
        let n_bits = 503543726;

        let chain_tip = ChainTip::new(prev_hash, n_bits, ntime);
        channel.set_chain_tip(chain_tip);

        let template = NewTemplate {
            template_id: 1,
            future_template: false,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        // match the original script format used to generate the coinbase_reward_outputs for the
        // expected job
        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0]; // SegWit version 0
        script_bytes.push(20); // Push 20 bytes (length of pubkey hash)
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        channel
            .on_new_template(template.clone(), coinbase_reward_outputs)
            .unwrap();

        assert!(!channel.job_store.has_future_jobs());

        let active_job = channel.get_active_job().unwrap().clone();

        // we know that the provided template + coinbase_reward_outputs should generate this
        // non-future job
        let expected_job = NewExtendedMiningJob {
            channel_id: 1,
            job_id: 1,
            min_ntime: Sv2Option::new(Some(ntime)),
            version: 536870912,
            version_rolling_allowed: true,
            coinbase_tx_prefix: vec![
                2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255, 38, 82, 0, 3, 47, 47, 47, 31,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_suffix: vec![
                255, 255, 255, 255, 2, 0, 242, 5, 42, 1, 0, 0, 0, 22, 0, 20, 235, 225, 183, 220,
                194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194, 8, 252, 0, 0, 0,
                0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209, 222,
                253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180, 139,
                235, 216, 54, 151, 78, 140, 249, 0, 0, 0, 0,
            ]
            .try_into()
            .unwrap(),
            merkle_path: vec![].try_into().unwrap(),
        };

        assert_eq!(active_job.get_job_message(), &expected_job);
    }

    #[test]
    fn test_coinbase_reward_outputs_sum_above_template_value() {
        // note:
        // the messages on this test were collected from a sane message flow
        // we use them as test vectors to assert correct behavior of job creation

        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
            0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        let template = NewTemplate {
            template_id: 1,
            future_template: true,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0]; // SegWit version 0
        script_bytes.push(20); // Push 20 bytes (length of pubkey hash)
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);

        let invalid_coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE + 1), /* oops: one too many extra
                                                                      * sats */
            script_pubkey: script,
        }];

        let res = channel.on_new_template(template.clone(), invalid_coinbase_reward_outputs);

        assert!(res.is_err());
        assert!(!channel.job_store.has_future_jobs());
    }

    #[test]
    fn test_share_validation_block_found() {
        // note:
        // the messages on this test were collected from a sane message flow
        // we use them as test vectors to assert correct behavior of job creation and share
        // validation

        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 8u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        // channel target: 04325c53ef368eb04325c53ef368eb04325c53ef368eb04325c53ef368eb0431

        let template_id = 1;
        let template = NewTemplate {
            template_id,
            future_template: false,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        // match the original script format used to generate the coinbase_reward_outputs for the
        // expected job
        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0]; // SegWit version 0
        script_bytes.push(20); // Push 20 bytes (length of pubkey hash)
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        // network target: 7fffff0000000000000000000000000000000000000000000000000000000000
        let ntime = 1745596910;
        let prev_hash = [
            251, 175, 106, 40, 35, 87, 122, 90, 58, 51, 78, 32, 202, 236, 228, 36, 154, 174, 206,
            144, 147, 195, 21, 224, 195, 103, 214, 189, 51, 190, 24, 98,
        ]
        .into();
        let n_bits = 545259519;
        let chain_tip = ChainTip::new(prev_hash, n_bits, ntime);
        channel.set_chain_tip(chain_tip);

        // prepare channel with non-future job
        channel
            .on_new_template(template.clone(), coinbase_reward_outputs)
            .unwrap();

        // this share has hash 4c68f79a585c8b609e9b43113f73311eada20ec88a70a999406267db3499f1d9
        // which satisfies network target
        // 7fffff0000000000000000000000000000000000000000000000000000000000
        let share_valid_block = SubmitSharesExtended {
            channel_id,
            sequence_number: 0,
            job_id: 1,
            nonce: 8,
            ntime: 1745596971,
            version: 536870912,
            extranonce: vec![1, 0, 0, 0, 0, 0, 0, 0].try_into().unwrap(),
        };

        let res = channel.validate_share(share_valid_block.clone());

        assert!(matches!(
            res,
            Ok(ShareValidationResult::BlockFound(_, _, _))
        ));
        assert_eq!(channel.get_share_accounting().get_blocks_found(), 1);

        // re-submitting the same valid block must be rejected as duplicate
        let res = channel.validate_share(share_valid_block);
        assert!(matches!(
            res.unwrap_err(),
            ShareValidationError::DuplicateShare
        ));
        assert_eq!(channel.get_share_accounting().get_blocks_found(), 1);
    }

    #[test]
    fn test_share_validation_does_not_meet_target() {
        // note:
        // the messages on this test were collected from a sane message flow
        // we use them as test vectors to assert correct behavior of job creation and share
        // validation

        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 100.0; // bigger hashrate to get higher difficulty
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 8u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        // channel target: 000aebbc990fff5144366f000aebbc990fff5144366f000aebbc990fff514435

        let template_id = 1;
        let template = NewTemplate {
            template_id,
            future_template: false,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        // match the original script format used to generate the coinbase_reward_outputs for the
        // expected job
        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0]; // SegWit version 0
        script_bytes.push(20); // Push 20 bytes (length of pubkey hash)
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        // network target: 000000000000d7c0000000000000000000000000000000000000000000000000
        let ntime = 1745596910;
        let prev_hash = [
            154, 124, 239, 231, 221, 122, 160, 173, 164, 175, 87, 33, 74, 214, 191, 107, 73, 34, 0,
            162, 227, 16, 44, 40, 33, 73, 0, 0, 0, 0, 0, 0,
        ]
        .into();
        let n_bits = 453040064;
        let chain_tip = ChainTip::new(prev_hash, n_bits, ntime);
        channel.set_chain_tip(chain_tip);

        // prepare channel with non-future job
        channel
            .on_new_template(template.clone(), coinbase_reward_outputs)
            .unwrap();

        // this share has hash d5767872f3a26e7f9f21cd968f27cfdb8b4061bb9ce0959852594ee8620f4efb
        // which does not meet the channel target
        // 000aebbc990fff5144366f000aebbc990fff5144366f000aebbc990fff514435
        let share_low_diff = SubmitSharesExtended {
            channel_id,
            sequence_number: 0,
            job_id: 1,
            nonce: 0,
            ntime: 1745596971,
            version: 536870912,
            extranonce: vec![1, 0, 0, 0, 0, 0, 0, 0].try_into().unwrap(),
        };

        let res = channel.validate_share(share_low_diff);

        assert!(matches!(
            res.unwrap_err(),
            ShareValidationError::DoesNotMeetTarget
        ));
    }

    #[test]
    fn test_share_validation_valid_share() {
        // note:
        // the messages on this test were collected from a sane message flow
        // we use them as test vectors to assert correct behavior of job creation and share
        // validation

        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1_000.0; // bigger hashrate to get higher difficulty
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 8u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        // channel target is:
        // 0001179d9861a761ffdadd11c307c4fc04eea3a418f7d687584e4434af158205

        let template_id = 1;
        let template = NewTemplate {
            template_id,
            future_template: false,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        // match the original script format used to generate the coinbase_reward_outputs for the
        // expected job
        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0]; // SegWit version 0
        script_bytes.push(20); // Push 20 bytes (length of pubkey hash)
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        // network tarkget is: 000000000000d7c0000000000000000000000000000000000000000000000000
        let n_bits = 453040064;
        let ntime = 1745611105;
        let prev_hash = [
            23, 205, 72, 134, 153, 86, 220, 153, 224, 28, 216, 146, 228, 120, 227, 157, 213, 99,
            160, 163, 128, 59, 139, 190, 158, 62, 0, 0, 0, 0, 0, 0,
        ]
        .into();
        let chain_tip = ChainTip::new(prev_hash, n_bits, ntime);
        channel.set_chain_tip(chain_tip);

        // prepare channel with non-future job
        channel
            .on_new_template(template.clone(), coinbase_reward_outputs)
            .unwrap();

        // this share has hash 000004f9d35777e4d56eedc20b1d05d251a7c0ed0b4e3013b5a809852844e218
        // which does meet the channel target
        // 0001179d9861a761ffdadd11c307c4fc04eea3a418f7d687584e4434af158205
        // but does not meet network target
        // 000000000000d7c0000000000000000000000000000000000000000000000000
        let valid_share = SubmitSharesExtended {
            channel_id,
            sequence_number: 1,
            job_id: 1,
            nonce: 51208,
            ntime: 1745611105,
            version: 536870912,
            extranonce: vec![1, 0, 0, 0, 0, 0, 0, 0].try_into().unwrap(),
        };

        let res = channel.validate_share(valid_share);
        assert!(matches!(res, Ok(ShareValidationResult::Valid(_))));

        // try to cheat by re-submitting the same share
        // with a different sequence number
        let repeated_share = SubmitSharesExtended {
            channel_id,
            sequence_number: 2,
            job_id: 1,
            nonce: 51208,
            ntime: 1745611105,
            version: 536870912,
            extranonce: vec![1, 0, 0, 0, 0, 0, 0, 0].try_into().unwrap(),
        };

        let res = channel.validate_share(repeated_share);

        // assert duplicate share is rejected
        assert!(matches!(res, Err(ShareValidationError::DuplicateShare)));
    }

    #[test]
    fn test_new_clamps_target_to_max_target() {
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [0, 0, 0, 1].to_vec();
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let expected_share_per_minute = 1.0;
        let very_small_hashrate = 0.1;
        let job_store = DefaultJobStore::new();

        // less permissive max_target to exercise constructor clamp path
        let not_so_permissive_max_target = Target::from_le_bytes([
            0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
            0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
            0xff, 0xff, 0xff, 0x00,
        ]);

        let channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            not_so_permissive_max_target,
            very_small_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        assert_eq!(
            channel.get_requested_max_target(),
            &not_so_permissive_max_target
        );
        assert_eq!(channel.get_target(), &not_so_permissive_max_target);
    }

    #[test]
    fn test_update_channel() {
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [
            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
            0, 0, 0, 0, 0, 0, 1,
        ]
        .to_vec();
        let expected_share_per_minute = 1.0;
        let initial_hashrate = 10.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        // this is the most permissive possible max_target
        let max_target = Target::from_le_bytes([0xff; 32]);

        // Create a channel with initial hashrate
        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix).unwrap(),
            max_target,
            initial_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        // Get the initial target
        let initial_target = channel.get_target().clone();

        // Update the channel with a new hashrate (higher)
        let new_hashrate = 100.0;
        channel
            .update_channel(new_hashrate, Some(max_target))
            .unwrap();

        // Get the new target after update
        let new_target = channel.get_target().clone();

        // The target should be different after updating with a different hashrate
        // old target: 006d0b803685c01b42e00da17006d0b803685c01b42e00da17006d0b803685bf
        // new target: 000aebbc990fff5144366f000aebbc990fff5144366f000aebbc990fff514435
        assert_ne!(initial_target, new_target);

        // The nominal hashrate should be updated
        assert_eq!(channel.get_nominal_hashrate(), new_hashrate);

        // Test invalid hashrate (negative)
        let result = channel.update_channel(-1.0, Some(max_target));
        assert!(result.is_err());
        assert!(matches!(
            result,
            Err(ExtendedChannelError::InvalidNominalHashrate)
        ));

        // Create a not so permissive max_target so we can test a target that exceeds it
        let not_so_permissive_max_target = Target::from_le_bytes([
            0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
            0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
            0xff, 0xff, 0xff, 0x00,
        ]);

        // Update with a hashrate that would compute a target exceeding max_target.
        // The channel should clamp to not_so_permissive_max_target instead of erroring.
        // calculated target: 2492492492492492492492492492492492492492492492492492492492492491
        // max target:        00ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
        let very_small_hashrate = 0.1;
        let result =
            channel.update_channel(very_small_hashrate, Some(not_so_permissive_max_target));
        assert!(result.is_ok());
        assert_eq!(channel.get_target(), &not_so_permissive_max_target);

        // Test successful update with not_so_permissive_max_target
        // new target: 0001179d9861a761ffdadd11c307c4fc04eea3a418f7d687584e4434af158205
        // max target: 00ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
        let sufficiently_big_hashrate = 1000.0;
        let result = channel.update_channel(
            sufficiently_big_hashrate,
            Some(not_so_permissive_max_target),
        );
        assert!(result.is_ok());
    }

    #[test]
    fn test_update_extranonce_prefix() {
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = [0, 0, 0, 0, 0, 0, 0, 1].to_vec();
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1_000.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        let current_extranonce_prefix = channel.get_extranonce_prefix();
        assert_eq!(current_extranonce_prefix, extranonce_prefix.as_slice());

        let new_extranonce_prefix = [0, 0, 0, 0, 0, 0, 0, 0, 0, 2].to_vec();

        channel
            .set_extranonce_prefix(
                AllocatedExtranoncePrefix::for_test(new_extranonce_prefix.clone()).unwrap(),
            )
            .unwrap();
        let current_extranonce_prefix = channel.get_extranonce_prefix();
        assert_eq!(current_extranonce_prefix, new_extranonce_prefix.as_slice());

        let new_extranonce_prefix_too_large = [
            83, 116, 114, 97, 116, 117, 109, 32, 86, 50, 32, 83, 82, 73, 32, 80, 111, 111, 108, 0,
            0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0,
        ]
        .to_vec();

        // too-large extranonce prefixes are rejected at the wire boundary
        assert!(matches!(
            ExtranoncePrefix::from_wire(new_extranonce_prefix_too_large.clone()),
            Err(ExtranoncePrefixError::ExceedsMaxLength)
        ));
    }

    #[test]
    fn test_on_group_channel_job_assigns_extranonce_prefix_to_future_job() {
        // Test that on_group_channel_job assigns the channel's extranonce prefix
        // to a future job that came from a group channel (with empty prefix)
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let channel_extranonce_prefix = vec![1, 2, 3, 4, 5, 6, 7];
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(channel_extranonce_prefix.clone()).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        let template = NewTemplate {
            template_id: 1,
            future_template: true,
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0];
        script_bytes.push(20);
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        // Create a job with empty extranonce prefix (as group channels do)
        let group_job = ExtendedJob::from_template(
            template.clone(),
            vec![], // empty extranonce prefix from group channel
            coinbase_reward_outputs,
            vec![],
            vec![],
            NewExtendedMiningJob {
                channel_id,
                job_id: 1,
                min_ntime: Sv2Option::new(None),
                version: template.version,
                version_rolling_allowed,
                coinbase_tx_prefix: vec![].try_into().unwrap(),
                coinbase_tx_suffix: vec![].try_into().unwrap(),
                merkle_path: vec![].try_into().unwrap(),
            },
        )
        .unwrap();

        // Verify the job has empty extranonce prefix initially
        assert_eq!(group_job.get_extranonce_prefix(), &vec![]);

        assert!(!channel.job_store.has_future_jobs());

        // Call on_group_channel_job to assign this channel's extranonce prefix
        channel.on_group_channel_job(group_job).unwrap();

        // Verify the job was added to future jobs
        assert!(channel.job_store.has_future_jobs());

        // Verify the job now has the channel's extranonce prefix assigned
        let future_job_id = channel
            .get_future_job_id_from_template_id(template.template_id)
            .unwrap();
        let stored_job = channel.get_future_job(future_job_id).unwrap();
        assert_eq!(
            stored_job.get_extranonce_prefix(),
            &channel_extranonce_prefix
        );
    }

    #[test]
    fn test_on_group_channel_job_assigns_extranonce_prefix_to_active_job() {
        // Test that on_group_channel_job assigns the channel's extranonce prefix
        // to an active (non-future) job from a group channel
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let channel_extranonce_prefix = vec![10, 20, 30, 40, 50];
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(channel_extranonce_prefix.clone()).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        let template = NewTemplate {
            template_id: 1,
            future_template: false, // non-future/active job
            version: 536870912,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![82, 0].try_into().unwrap(),
            coinbase_tx_input_sequence: 4294967295,
            coinbase_tx_value_remaining: SATS_AVAILABLE_IN_TEMPLATE,
            coinbase_tx_outputs_count: 1,
            coinbase_tx_outputs: vec![
                0, 0, 0, 0, 0, 0, 0, 0, 38, 106, 36, 170, 33, 169, 237, 226, 246, 28, 63, 113, 209,
                222, 253, 63, 169, 153, 223, 163, 105, 83, 117, 92, 105, 6, 137, 121, 153, 98, 180,
                139, 235, 216, 54, 151, 78, 140, 249,
            ]
            .try_into()
            .unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        let pubkey_hash = [
            235, 225, 183, 220, 194, 147, 204, 170, 14, 231, 67, 168, 111, 137, 223, 130, 88, 194,
            8, 252,
        ];
        let mut script_bytes = vec![0];
        script_bytes.push(20);
        script_bytes.extend_from_slice(&pubkey_hash);
        let script = ScriptBuf::from(script_bytes);
        let coinbase_reward_outputs = vec![TxOut {
            value: Amount::from_sat(SATS_AVAILABLE_IN_TEMPLATE),
            script_pubkey: script,
        }];

        let ntime = 1746839905;
        // Create a job with empty extranonce prefix (as group channels do)
        let group_job = ExtendedJob::from_template(
            template.clone(),
            vec![], // empty extranonce prefix from group channel
            coinbase_reward_outputs,
            vec![],
            vec![],
            NewExtendedMiningJob {
                channel_id,
                job_id: 1,
                min_ntime: Sv2Option::new(Some(ntime)),
                version: template.version,
                version_rolling_allowed,
                coinbase_tx_prefix: vec![].try_into().unwrap(),
                coinbase_tx_suffix: vec![].try_into().unwrap(),
                merkle_path: vec![].try_into().unwrap(),
            },
        )
        .unwrap();

        // Set chain tip to enable active job storage
        channel.set_chain_tip(ChainTip::new(U256::from([0; 32]), 0, ntime));

        // Verify the job has empty extranonce prefix initially
        assert_eq!(group_job.get_extranonce_prefix(), &vec![]);
        assert!(channel.get_active_job().is_none());

        // Call on_group_channel_job
        channel.on_group_channel_job(group_job).unwrap();

        // Verify the job was added as active job with the channel's extranonce prefix
        let active_job = channel.get_active_job().unwrap();
        assert_eq!(
            active_job.get_extranonce_prefix(),
            &channel_extranonce_prefix
        );
    }

    #[test]
    fn test_on_group_channel_job_rejects_custom_mining_job() {
        // Test that on_group_channel_job returns InvalidJobOrigin error for SetCustomMiningJob
        // because custom jobs don't come from group channels
        let channel_id = 1;
        let user_identity = "user_identity".to_string();
        let extranonce_prefix = vec![1, 2, 3, 4];
        let max_target = Target::from_le_bytes([0xff; 32]);
        let expected_share_per_minute = 1.0;
        let nominal_hashrate = 1.0;
        let version_rolling_allowed = true;
        let rollable_extranonce_size = 4u16;
        let share_batch_size = 100;
        let job_store = DefaultJobStore::new();

        let mut channel = ExtendedChannel::new(
            channel_id,
            user_identity,
            ExtranoncePrefix::from_wire(extranonce_prefix.clone()).unwrap(),
            max_target,
            nominal_hashrate,
            version_rolling_allowed,
            rollable_extranonce_size,
            share_batch_size,
            expected_share_per_minute,
            job_store,
            None,
            None,
        )
        .unwrap();

        // Create a job from SetCustomMiningJob (not from group channel)
        let custom_job = SetCustomMiningJob {
            channel_id,
            request_id: 0,
            token: vec![].try_into().unwrap(),
            version: 536870912,
            prev_hash: [0; 32].into(),
            min_ntime: 1746839905,
            nbits: 503543726,
            coinbase_tx_version: 2,
            coinbase_prefix: vec![].try_into().unwrap(),
            coinbase_tx_input_n_sequence: 4294967295,
            coinbase_tx_outputs: vec![].try_into().unwrap(),
            coinbase_tx_locktime: 0,
            merkle_path: vec![].try_into().unwrap(),
        };

        let extended_job = ExtendedJob::from_custom_job(
            custom_job,
            vec![], // empty extranonce prefix
            vec![],
            vec![],
            vec![],
            NewExtendedMiningJob {
                channel_id,
                job_id: 1,
                min_ntime: Sv2Option::new(None),
                version: 536870912,
                version_rolling_allowed,
                coinbase_tx_prefix: vec![].try_into().unwrap(),
                coinbase_tx_suffix: vec![].try_into().unwrap(),
                merkle_path: vec![].try_into().unwrap(),
            },
        );

        // Call on_group_channel_job and expect InvalidJobOrigin error
        // because custom jobs don't come from group channels
        let result = channel.on_group_channel_job(extended_job);
        assert!(result.is_err());
        assert!(matches!(
            result.unwrap_err(),
            ExtendedChannelError::InvalidJobOrigin
        ));
    }
}