pepper_sync/

wallet.rs

//! Module for wallet structs and types generated by the sync engine from block chain data or to track the wallet's
//! sync status.
//! The structs will be (or be transposed into) the fundamental wallet components for the wallet interfacing with this
//! sync engine.

use std::{
    collections::{BTreeMap, BTreeSet},
    convert::Infallible,
    fmt::Debug,
    marker::PhantomData,
    ops::Range,
    sync::atomic::{self, AtomicU8},
};

use incrementalmerkletree::Position;
use orchard::tree::MerkleHashOrchard;
use shardtree::{ShardTree, store::memory::MemoryShardStore};
use tokio::sync::mpsc;
use zcash_address::unified::ParseError;
use zcash_keys::{address::UnifiedAddress, encoding::encode_payment_address};
use zcash_primitives::{block::BlockHash, transaction::TxId};
use zcash_protocol::{
    PoolType, ShieldedPool,
    consensus::{self, BlockHeight},
    memo::Memo,
    value::Zatoshis,
};
use zcash_transparent::address::Script;
use zcash_transparent::bundle::OutPoint;

use zingo_netutils::lightwallet_protocol::CompactBlock;
use zingo_status::confirmation_status::ConfirmationStatus;

use crate::{
    client::FetchRequest,
    error::{ServerError, SyncModeError},
    keys::{self, KeyId, transparent::TransparentAddressId},
    scan::compact_blocks::calculate_block_tree_bounds,
    shardtree_ext::{CheckpointAppendOutcome, ShardTreeExt as _},
    sync::{SHARDTREE_CHECKPOINT_ROLLING_WINDOW_SIZE, ScanPriority, ScanRange},
    utils::{block, transaction},
    witness,
};

pub mod traits;

#[cfg(feature = "wallet_essentials")]
pub mod serialization;

/// A block, or a transaction in it, that scanning must reach. A target names a block height and, when a particular
/// transaction is wanted, its txid. Two targets naming the same block height and txid are the same target.
///
/// The blocks around a target are prioritised for scanning: a narrow range by default, and the whole shard of each
/// pool the target's transaction was found to hold notes of, so those notes become spendable.
#[derive(Debug, Clone, Copy)]
pub struct ScanTarget {
    block_height: BlockHeight,
    txid: Option<TxId>,
    pools: ScanTargetPools,
    origin: ScanTargetOrigin,
}

// Where a scan target came from, which decides what a transaction the server does not serve means.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ScanTargetOrigin {
    // Trial decryption, spend detection or transparent address discovery. A transaction the server does not serve
    // is an inconsistency in the served data.
    Internal,
    // `crate::add_scan_targets`. A transaction the server does not serve, or a block height outside the chain, is a
    // consumer error and the target is dropped.
    External,
}

// The shielded pools a scan target's transaction was found to hold notes of, as bits of a byte.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub(crate) struct ScanTargetPools(u8);

impl ScanTargetPools {
    const ALL_POOLS: [ShieldedPool; 3] = [
        ShieldedPool::Sapling,
        ShieldedPool::Orchard,
        ShieldedPool::Ironwood,
    ];

    const fn bit(pool: ShieldedPool) -> u8 {
        match pool {
            ShieldedPool::Sapling => 1,
            ShieldedPool::Orchard => 1 << 1,
            ShieldedPool::Ironwood => 1 << 2,
        }
    }

    #[cfg(feature = "wallet_essentials")]
    pub(crate) fn from_bits(bits: u8) -> Option<Self> {
        let known = Self::ALL_POOLS
            .into_iter()
            .fold(0, |known, pool| known | Self::bit(pool));
        (bits & !known == 0).then_some(Self(bits))
    }

    #[cfg(feature = "wallet_essentials")]
    pub(crate) fn bits(self) -> u8 {
        self.0
    }

    pub(crate) fn with(self, pool: ShieldedPool) -> Self {
        Self(self.0 | Self::bit(pool))
    }

    pub(crate) fn is_empty(self) -> bool {
        self.0 == 0
    }

    pub(crate) fn iter(self) -> impl Iterator<Item = ShieldedPool> {
        Self::ALL_POOLS
            .into_iter()
            .filter(move |&pool| self.0 & Self::bit(pool) != 0)
    }
}

impl ScanTarget {
    /// A target to add through [`crate::add_scan_targets`]. The blocks around `block_height` are prioritised for
    /// scanning, and the transaction `txid` is scanned there when given.
    #[must_use]
    pub fn new(block_height: BlockHeight, txid: Option<TxId>) -> Self {
        Self {
            block_height,
            txid,
            pools: ScanTargetPools::default(),
            origin: ScanTargetOrigin::External,
        }
    }

    pub(crate) fn internal(block_height: BlockHeight, txid: TxId) -> Self {
        Self {
            block_height,
            txid: Some(txid),
            pools: ScanTargetPools::default(),
            origin: ScanTargetOrigin::Internal,
        }
    }

    /// The block height of the target.
    #[must_use]
    pub fn block_height(&self) -> BlockHeight {
        self.block_height
    }

    /// The txid of the transaction to scan at the target's block height, when a particular one is wanted.
    #[must_use]
    pub fn txid(&self) -> Option<TxId> {
        self.txid
    }

    pub(crate) fn pools(&self) -> ScanTargetPools {
        self.pools
    }

    pub(crate) fn origin(&self) -> ScanTargetOrigin {
        self.origin
    }

    pub(crate) fn with_pool(self, pool: ShieldedPool) -> Self {
        Self {
            pools: self.pools.with(pool),
            ..self
        }
    }

    // The target that stands for both `self` and `other`, which name the same block height and txid: it holds the
    // pools of both, and it is internal where either is.
    fn merge(mut self, other: Self) -> Self {
        self.pools.0 |= other.pools.0;
        if other.origin == ScanTargetOrigin::Internal {
            self.origin = ScanTargetOrigin::Internal;
        }
        self
    }

    fn key(&self) -> (BlockHeight, Option<TxId>) {
        (self.block_height, self.txid)
    }
}

impl PartialEq for ScanTarget {
    fn eq(&self, other: &Self) -> bool {
        self.key() == other.key()
    }
}

impl Eq for ScanTarget {}

impl PartialOrd for ScanTarget {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for ScanTarget {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        self.key().cmp(&other.key())
    }
}

/// Initial sync state.
///
/// All fields will be reset when a new sync session starts.
#[derive(Debug, Clone)]
pub struct InitialSyncState {
    /// One block above the fully scanned wallet height at start of sync session.
    ///
    /// If chain height is not larger than fully scanned height when sync is called, this value will be set to chain
    /// height instead.
    pub(crate) sync_start_height: BlockHeight,
    /// The tree sizes of the fully scanned height and chain tip at start of sync session.
    pub(crate) wallet_tree_bounds: TreeBounds,
    /// Total number of blocks scanned in previous sync sessions.
    pub(crate) previously_scanned_blocks: u32,
    /// Total number of sapling outputs scanned in previous sync sessions.
    pub(crate) previously_scanned_sapling_outputs: u32,
    /// Total number of orchard outputs scanned in previous sync sessions.
    pub(crate) previously_scanned_orchard_outputs: u32,
    /// Total number of ironwood outputs scanned in previous sync sessions.
    pub(crate) previously_scanned_ironwood_outputs: u32,
}

impl InitialSyncState {
    /// Create new `InitialSyncState`
    #[must_use]
    pub fn new() -> Self {
        InitialSyncState {
            sync_start_height: 0.into(),
            wallet_tree_bounds: TreeBounds {
                sapling_initial_tree_size: 0,
                sapling_final_tree_size: 0,
                orchard_initial_tree_size: 0,
                orchard_final_tree_size: 0,
                ironwood_initial_tree_size: 0,
                ironwood_final_tree_size: 0,
            },
            previously_scanned_blocks: 0,
            previously_scanned_sapling_outputs: 0,
            previously_scanned_orchard_outputs: 0,
            previously_scanned_ironwood_outputs: 0,
        }
    }
}

impl Default for InitialSyncState {
    fn default() -> Self {
        Self::new()
    }
}

/// Encapsulates the current state of sync
#[derive(Debug, Clone)]
pub struct SyncState {
    /// A vec of block ranges with scan priorities from wallet birthday to chain tip.
    /// In block height order with no overlaps or gaps.
    pub(crate) scan_ranges: Vec<ScanRange>,
    /// The block ranges that contain all sapling outputs of complete sapling shards.
    ///
    /// There is an edge case where a range may include two (or more) shards. However, this only occurs when the lower
    /// shards are already scanned so will cause no issues when punching in the higher scan priorites.
    pub(crate) sapling_shard_ranges: Vec<Range<BlockHeight>>,
    /// The block ranges that contain all orchard outputs of complete orchard shards.
    ///
    /// There is an edge case where a range may include two (or more) shards. However, this only occurs when the lower
    /// shards are already scanned so will cause no issues when punching in the higher scan priorites.
    pub(crate) orchard_shard_ranges: Vec<Range<BlockHeight>>,
    /// The block ranges that contain all ironwood outputs of complete ironwood shards.
    ///
    /// There is an edge case where a range may include two (or more) shards. However, this only occurs when the lower
    /// shards are already scanned so will cause no issues when punching in the higher scan priorites.
    pub(crate) ironwood_shard_ranges: Vec<Range<BlockHeight>>,
    /// Scan targets for relevant transactions to the wallet.
    pub(crate) scan_targets: BTreeSet<ScanTarget>,
    /// Initial sync state.
    pub(crate) initial_sync_state: InitialSyncState,
    /// Compact block transparent data is only scanned above this height. This includes checking transparent outputs
    /// against the wallet's in-use and gap addresses and mapping transparent inputs to the wallet's outpoint map.
    ///
    /// Set to the chain height when transparent address discovery completes at the start of a sync session, as it has
    /// located all relevant transactions at or below this height. Lowered if the wallet is truncated below this
    /// height, by a re-org or a chain height below the wallet's, as transparent address discovery does not cover the
    /// blocks scanned in place of the truncated blocks.
    ///
    /// Blocks mined during a sync session are above the floor and may still be unscanned when the session ends, so
    /// the transparent address discovery of the next sync session searches from the block above the floor.
    pub(crate) transparent_scan_floor: Option<BlockHeight>,
}

impl SyncState {
    /// Create new `SyncState`
    #[must_use]
    pub fn new() -> Self {
        SyncState {
            scan_ranges: Vec::new(),
            sapling_shard_ranges: Vec::new(),
            orchard_shard_ranges: Vec::new(),
            ironwood_shard_ranges: Vec::new(),
            scan_targets: BTreeSet::new(),
            initial_sync_state: InitialSyncState::new(),
            transparent_scan_floor: None,
        }
    }

    /// Scan ranges
    #[must_use]
    pub fn scan_ranges(&self) -> &[ScanRange] {
        &self.scan_ranges
    }

    /// Sapling shard ranges
    #[must_use]
    pub fn sapling_shard_ranges(&self) -> &[Range<BlockHeight>] {
        &self.sapling_shard_ranges
    }

    /// Orchard shard ranges
    #[must_use]
    pub fn orchard_shard_ranges(&self) -> &[Range<BlockHeight>] {
        &self.orchard_shard_ranges
    }

    /// Ironwood shard ranges
    #[must_use]
    pub fn ironwood_shard_ranges(&self) -> &[Range<BlockHeight>] {
        &self.ironwood_shard_ranges
    }

    /// The shard ranges of `pool`
    #[must_use]
    pub fn shard_ranges(&self, pool: ShieldedPool) -> &[Range<BlockHeight>] {
        match pool {
            ShieldedPool::Sapling => &self.sapling_shard_ranges,
            ShieldedPool::Orchard => &self.orchard_shard_ranges,
            ShieldedPool::Ironwood => &self.ironwood_shard_ranges,
        }
    }

    /// Returns true if all scan ranges are scanned.
    pub(crate) fn scan_complete(&self) -> bool {
        self.scan_ranges
            .iter()
            .all(|scan_range| scan_range.priority() == ScanPriority::Scanned)
    }

    /// Returns the block height at which all blocks equal to and below this height are scanned.
    /// Returns `None` if `self.scan_ranges` is empty.
    #[must_use]
    pub fn fully_scanned_height(&self) -> Option<BlockHeight> {
        if let Some(scan_range) = self
            .scan_ranges
            .iter()
            .find(|scan_range| scan_range.priority() != ScanPriority::Scanned)
        {
            Some(scan_range.block_range().start - 1)
        } else {
            self.scan_ranges
                .last()
                .map(|range| range.block_range().end - 1)
        }
    }

    /// Returns the highest block height that has been scanned.
    /// If no scan ranges have been scanned, returns the block below the wallet birthday.
    /// Returns `None` if `self.scan_ranges` is empty.
    #[must_use]
    pub fn highest_scanned_height(&self) -> Option<BlockHeight> {
        if let Some(last_scanned_range) = self.scan_ranges.iter().rfind(|scan_range| {
            scan_range.priority() == ScanPriority::Scanned
                || scan_range.priority() == ScanPriority::ScannedWithoutMapping
                || scan_range.priority() == ScanPriority::RefetchingNullifiers
        }) {
            Some(last_scanned_range.block_range().end - 1)
        } else {
            self.wallet_birthday().map(|start| start - 1)
        }
    }

    /// Returns the wallet birthday or `None` if `self.scan_ranges` is empty.
    ///
    #[must_use]
    pub fn wallet_birthday(&self) -> Option<BlockHeight> {
        self.scan_ranges
            .first()
            .map(|range| range.block_range().start)
    }

    /// - Inserts `scan_target`, merged into the target already held for the same block height and txid if any.
    pub(crate) fn insert_scan_target(&mut self, scan_target: ScanTarget) {
        let merged = self
            .scan_targets
            .take(&scan_target)
            .map_or(scan_target, |held| held.merge(scan_target));
        self.scan_targets.insert(merged);
    }

    /// Returns the last known chain height to the wallet or `None` if `self.scan_ranges` is empty.
    #[must_use]
    pub fn last_known_chain_height(&self) -> Option<BlockHeight> {
        self.scan_ranges
            .last()
            .map(|range| range.block_range().end - 1)
    }
}

impl Default for SyncState {
    fn default() -> Self {
        Self::new()
    }
}

/// Sync modes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SyncMode {
    /// Sync is not running.
    NotRunning,
    /// Sync is held in a paused state and the wallet guard is dropped.
    Paused,
    /// Sync is running.
    Running,
    /// Sync is shutting down.
    Shutdown,
}

impl SyncMode {
    /// Constructor from u8.
    ///
    /// Returns `None` if `mode` is not a valid enum variant.
    pub fn from_u8(mode: u8) -> Result<Self, SyncModeError> {
        match mode {
            0 => Ok(Self::NotRunning),
            1 => Ok(Self::Paused),
            2 => Ok(Self::Running),
            3 => Ok(Self::Shutdown),
            _ => Err(SyncModeError::InvalidSyncMode(mode)),
        }
    }

    /// Reads the mode held in `atomic_sync_mode`, failing when the byte is no variant of this enum.
    pub fn from_atomic_u8(atomic_sync_mode: &AtomicU8) -> Result<SyncMode, SyncModeError> {
        SyncMode::from_u8(atomic_sync_mode.load(atomic::Ordering::Acquire))
    }

    /// Returns the mode a completed scan leaves behind, which is `Shutdown` for a running engine and the same mode for every other.
    pub fn on_completion(self) -> Self {
        match self {
            Self::Running => Self::Shutdown,
            other => other,
        }
    }

    /// Replaces the mode held in `atomic_sync_mode` with `step` of it in one atomic exchange and returns the mode it replaced.
    pub fn apply(
        atomic_sync_mode: &AtomicU8,
        step: impl Fn(Self) -> Self,
    ) -> Result<Self, SyncModeError> {
        atomic_sync_mode
            .try_update(
                atomic::Ordering::AcqRel,
                atomic::Ordering::Acquire,
                |mode| Self::from_u8(mode).ok().map(|mode| step(mode) as u8),
            )
            .map_err(SyncModeError::InvalidSyncMode)
            .and_then(Self::from_u8)
    }

    /// Moves `atomic_sync_mode` from `from` to `to` when it holds `from` and returns the mode it held before.
    pub fn transition(
        atomic_sync_mode: &AtomicU8,
        from: Self,
        to: Self,
    ) -> Result<Self, SyncModeError> {
        Self::apply(
            atomic_sync_mode,
            |mode| if mode == from { to } else { mode },
        )
    }
}

/// Initial and final tree sizes.
#[derive(Debug, Clone, Copy)]
#[allow(missing_docs)]
pub struct TreeBounds {
    pub sapling_initial_tree_size: u32,
    pub sapling_final_tree_size: u32,
    pub orchard_initial_tree_size: u32,
    pub orchard_final_tree_size: u32,
    pub ironwood_initial_tree_size: u32,
    pub ironwood_final_tree_size: u32,
}

/// Output ID for a given pool type.
#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
pub struct OutputId {
    /// ID of associated transaction.
    txid: TxId,
    /// Index of output within the transactions bundle of the given pool type.
    output_index: u32,
}

impl OutputId {
    /// Creates new `OutputId` from parts.
    #[must_use]
    pub fn new(txid: TxId, output_index: u32) -> Self {
        OutputId { txid, output_index }
    }

    /// Transaction ID of output's associated transaction.
    #[must_use]
    pub fn txid(&self) -> TxId {
        self.txid
    }

    /// Index of output within the transactions bundle of the given pool type.
    #[must_use]
    pub fn output_index(&self) -> u32 {
        self.output_index
    }
}

impl std::fmt::Display for OutputId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{{
                txid: {}
                output index: {}
            }}",
            self.txid, self.output_index
        )
    }
}

impl From<&OutPoint> for OutputId {
    fn from(value: &OutPoint) -> Self {
        OutputId::new(*value.txid(), value.n())
    }
}

impl From<OutputId> for OutPoint {
    fn from(value: OutputId) -> Self {
        OutPoint::new(value.txid.into(), value.output_index)
    }
}

/// Binary tree map of nullifiers from transaction spends or actions
#[derive(Debug)]
pub struct NullifierMap {
    /// Sapling nullifer map
    pub sapling: BTreeMap<sapling_crypto::Nullifier, ScanTarget>,
    /// Orchard nullifer map
    pub orchard: BTreeMap<orchard::note::Nullifier, ScanTarget>,
    /// Ironwood nullifer map
    pub ironwood: BTreeMap<orchard::note::Nullifier, ScanTarget>,
}

impl NullifierMap {
    /// Construct new nullifier map.
    #[must_use]
    pub fn new() -> Self {
        Self {
            sapling: BTreeMap::new(),
            orchard: BTreeMap::new(),
            ironwood: BTreeMap::new(),
        }
    }

    /// Clear nullifier map.
    pub fn clear(&mut self) {
        self.sapling.clear();
        self.orchard.clear();
        self.ironwood.clear();
    }
}

impl Default for NullifierMap {
    fn default() -> Self {
        Self::new()
    }
}

/// Wallet block data
#[derive(Debug, Clone)]
pub struct WalletBlock {
    pub(crate) block_height: BlockHeight,
    pub(crate) block_hash: BlockHash,
    pub(crate) prev_hash: BlockHash,
    pub(crate) time: u32,
    pub(crate) txids: Vec<TxId>,
    pub(crate) tree_bounds: TreeBounds,
}

impl WalletBlock {
    pub(crate) async fn from_compact_block(
        consensus_parameters: &impl consensus::Parameters,
        fetch_request_sender: mpsc::UnboundedSender<FetchRequest>,
        block: &CompactBlock,
    ) -> Result<Self, ServerError> {
        let tree_bounds =
            calculate_block_tree_bounds(consensus_parameters, fetch_request_sender, block).await?;

        Ok(Self {
            block_height: block::get_compact_height(block),
            block_hash: block::get_compact_hash(block),
            prev_hash: block::get_compact_prev_hash(block),
            time: block.time,
            txids: block
                .vtx
                .iter()
                .map(transaction::get_compact_txid)
                .collect(),
            tree_bounds,
        })
    }

    /// Block height.
    #[must_use]
    pub fn block_height(&self) -> BlockHeight {
        self.block_height
    }

    /// Block hash.
    #[must_use]
    pub fn block_hash(&self) -> BlockHash {
        self.block_hash
    }

    /// Previous block hash.
    #[must_use]
    pub fn prev_hash(&self) -> BlockHash {
        self.prev_hash
    }

    /// Time block was mined.
    #[must_use]
    pub fn time(&self) -> u32 {
        self.time
    }

    /// Transaction IDs of transactions in the block.
    #[must_use]
    pub fn txids(&self) -> &[TxId] {
        &self.txids
    }

    /// Tree size bounds
    #[must_use]
    pub fn tree_bounds(&self) -> TreeBounds {
        self.tree_bounds
    }
}

/// Wallet transaction
pub struct WalletTransaction {
    pub(crate) txid: TxId,
    pub(crate) status: ConfirmationStatus,
    pub(crate) transaction: zcash_primitives::transaction::Transaction,
    pub(crate) datetime: u32,
    pub(crate) transparent_coins: Vec<TransparentCoin>,
    pub(crate) sapling_notes: Vec<SaplingNote>,
    pub(crate) orchard_notes: Vec<OrchardNote>,
    pub(crate) ironwood_notes: Vec<IronwoodNote>,
    pub(crate) outgoing_sapling_notes: Vec<OutgoingSaplingNote>,
    pub(crate) outgoing_orchard_notes: Vec<OutgoingOrchardNote>,
    pub(crate) outgoing_ironwood_notes: Vec<OutgoingIronwoodNote>,
}

impl WalletTransaction {
    /// Transaction ID
    #[must_use]
    pub fn txid(&self) -> TxId {
        self.txid
    }

    /// Confirmation status
    #[must_use]
    pub fn status(&self) -> ConfirmationStatus {
        self.status
    }

    /// [`zcash_primitives::transaction::Transaction`]
    #[must_use]
    pub fn transaction(&self) -> &zcash_primitives::transaction::Transaction {
        &self.transaction
    }

    /// Datetime. In form of seconds since unix epoch.
    #[must_use]
    pub fn datetime(&self) -> u32 {
        self.datetime
    }

    /// Transparent coins
    #[must_use]
    pub fn transparent_coins(&self) -> &[TransparentCoin] {
        &self.transparent_coins
    }

    /// Transparent coins mutable
    pub fn transparent_coins_mut(&mut self) -> Vec<&mut TransparentCoin> {
        self.transparent_coins.iter_mut().collect()
    }

    /// Sapling notes
    #[must_use]
    pub fn sapling_notes(&self) -> &[SaplingNote] {
        &self.sapling_notes
    }

    /// Sapling notes mutable
    pub fn sapling_notes_mut(&mut self) -> Vec<&mut SaplingNote> {
        self.sapling_notes.iter_mut().collect()
    }

    /// Orchard notes
    #[must_use]
    pub fn orchard_notes(&self) -> &[OrchardNote] {
        &self.orchard_notes
    }

    /// Orchard notes mutable
    pub fn orchard_notes_mut(&mut self) -> Vec<&mut OrchardNote> {
        self.orchard_notes.iter_mut().collect()
    }

    /// Ironwood notes
    #[must_use]
    pub fn ironwood_notes(&self) -> &[IronwoodNote] {
        &self.ironwood_notes
    }

    /// Ironwood notes mutable
    pub fn ironwood_notes_mut(&mut self) -> Vec<&mut IronwoodNote> {
        self.ironwood_notes.iter_mut().collect()
    }

    /// Outgoing sapling notes
    #[must_use]
    pub fn outgoing_sapling_notes(&self) -> &[OutgoingSaplingNote] {
        &self.outgoing_sapling_notes
    }

    /// Outgoing orchard notes
    #[must_use]
    pub fn outgoing_orchard_notes(&self) -> &[OutgoingOrchardNote] {
        &self.outgoing_orchard_notes
    }

    /// Outgoing ironwood notes
    #[must_use]
    pub fn outgoing_ironwood_notes(&self) -> &[OutgoingIronwoodNote] {
        &self.outgoing_ironwood_notes
    }

    /// Returns nullifers from sapling bundle.
    /// Returns empty vec if bundle is `None`.
    pub fn sapling_nullifiers(&self) -> Vec<&sapling_crypto::Nullifier> {
        self.transaction
            .sapling_bundle()
            .map_or_else(Vec::new, |bundle| {
                bundle
                    .shielded_spends()
                    .iter()
                    .map(|spend| spend.nullifier())
                    .collect::<Vec<_>>()
            })
    }

    /// Returns nullifers from orchard bundle.
    /// Returns empty vec if bundle is `None`.
    pub fn orchard_nullifiers(&self) -> Vec<&orchard::note::Nullifier> {
        self.transaction
            .orchard_bundle()
            .map_or_else(Vec::new, |bundle| {
                bundle
                    .actions()
                    .iter()
                    .map(orchard::Action::nullifier)
                    .collect::<Vec<_>>()
            })
    }

    /// Returns nullifers from ironwood bundle.
    /// Returns empty vec if bundle is `None`.
    pub fn ironwood_nullifiers(&self) -> Vec<&orchard::note::Nullifier> {
        self.transaction
            .ironwood_bundle()
            .map_or_else(Vec::new, |bundle| {
                bundle
                    .actions()
                    .iter()
                    .map(orchard::Action::nullifier)
                    .collect::<Vec<_>>()
            })
    }

    /// Returns outpoints from transparent bundle.
    /// Returns empty vec if bundle is `None`.
    pub fn outpoints(&self) -> Vec<&OutPoint> {
        self.transaction
            .transparent_bundle()
            .map_or_else(Vec::new, |bundle| {
                bundle
                    .vin
                    .iter()
                    .map(zcash_transparent::bundle::TxIn::prevout)
                    .collect::<Vec<_>>()
            })
    }

    /// Updates transaction status if `status` is a valid update for the current transaction status.
    /// For example, if `status` is `Mempool` but the current transaction status is `Confirmed`, the status will remain
    /// unchanged.
    /// A `Failed` transaction may return to `Mempool` status, as being observed in the mempool is
    /// proof the transaction was not rejected or expired.
    /// `datetime` refers to the time in which the status was updated, or the time the block was mined when updating
    /// to `Confirmed` status.
    /// If `fail_confirmed` is set, a confirmed transaction can be set to failed (i.e. during re-org truncation).
    pub fn update_status(
        &mut self,
        status: ConfirmationStatus,
        datetime: u32,
        fail_confirmed: bool,
    ) {
        match status {
            ConfirmationStatus::Transmitted(_)
                if matches!(self.status(), ConfirmationStatus::Calculated(_)) =>
            {
                self.status = status;
                self.datetime = datetime;
            }
            ConfirmationStatus::Mempool(_)
                if matches!(
                    self.status(),
                    ConfirmationStatus::Calculated(_)
                        | ConfirmationStatus::Transmitted(_)
                        | ConfirmationStatus::Failed(_)
                ) =>
            {
                self.status = status;
                self.datetime = datetime;
            }
            ConfirmationStatus::Confirmed(_)
                if matches!(
                    self.status(),
                    ConfirmationStatus::Calculated(_)
                        | ConfirmationStatus::Transmitted(_)
                        | ConfirmationStatus::Mempool(_)
                ) =>
            {
                self.status = status;
                self.datetime = datetime;
            }
            ConfirmationStatus::Failed(_)
                if (fail_confirmed && !matches!(self.status(), ConfirmationStatus::Failed(_)))
                    || self.status().is_pending() =>
            {
                self.status = status;
                self.datetime = datetime;
            }
            _ => (),
        }
    }
}

#[cfg(any(test, feature = "test-features"))]
impl WalletTransaction {
    /// Creates a minimal `WalletTransaction` for testing purposes.
    ///
    /// Constructs a valid v5 transaction with empty bundles and the given `txid` and `status`.
    /// The transaction's expiry height is set to 0 (never expires).
    pub fn new_for_test(txid: TxId, status: ConfirmationStatus) -> Self {
        Self::new_for_test_with_expiry(txid, status, BlockHeight::from_u32(0))
    }

    /// Creates a minimal `WalletTransaction` for testing purposes, with the given expiry height.
    ///
    /// Constructs a valid v5 transaction with empty bundles and the given `txid` and `status`.
    pub fn new_for_test_with_expiry(
        txid: TxId,
        status: ConfirmationStatus,
        expiry_height: BlockHeight,
    ) -> Self {
        use zcash_primitives::transaction::{TransactionData, TxVersion};
        use zcash_protocol::consensus::BranchId;

        let transaction = TransactionData::from_parts(
            TxVersion::V6,
            BranchId::Nu6_3,
            0,
            expiry_height,
            None,
            None,
            None,
            None,
        )
        .freeze()
        .expect("empty v5 transaction should always be valid");

        Self {
            txid,
            status,
            transaction,
            datetime: 0,
            transparent_coins: Vec::new(),
            sapling_notes: Vec::new(),
            orchard_notes: Vec::new(),
            ironwood_notes: Vec::new(),
            outgoing_sapling_notes: Vec::new(),
            outgoing_orchard_notes: Vec::new(),
            outgoing_ironwood_notes: Vec::new(),
        }
    }

    /// As [`Self::new_for_test`], with received sapling notes attached.
    #[must_use]
    pub fn with_sapling_notes_for_test(mut self, sapling_notes: Vec<SaplingNote>) -> Self {
        self.sapling_notes = sapling_notes;
        self
    }

    /// As [`Self::new_for_test`], with outgoing sapling notes attached.
    #[must_use]
    pub fn with_outgoing_sapling_notes_for_test(
        mut self,
        outgoing_sapling_notes: Vec<OutgoingSaplingNote>,
    ) -> Self {
        self.outgoing_sapling_notes = outgoing_sapling_notes;
        self
    }

    /// As [`Self::new_for_test`], with received transparent coins attached.
    #[must_use]
    pub fn with_transparent_coins_for_test(
        mut self,
        transparent_coins: Vec<TransparentCoin>,
    ) -> Self {
        self.transparent_coins = transparent_coins;
        self
    }

    /// As [`Self::new_for_test`], with received and outgoing orchard notes
    /// attached, for tests exercising summary/value-transfer derivation
    /// without a chain.
    pub fn new_for_test_with_orchard_notes(
        txid: TxId,
        status: ConfirmationStatus,
        orchard_notes: Vec<OrchardNote>,
        outgoing_orchard_notes: Vec<OutgoingOrchardNote>,
    ) -> Self {
        let mut transaction = Self::new_for_test(txid, status);
        transaction.orchard_notes = orchard_notes;
        transaction.outgoing_orchard_notes = outgoing_orchard_notes;
        transaction
    }

    /// As [`Self::new_for_test`], with received and outgoing ironwood notes
    /// attached, for tests exercising summary/value-transfer derivation
    /// without a chain.
    pub fn new_for_test_with_ironwood_notes(
        txid: TxId,
        status: ConfirmationStatus,
        ironwood_notes: Vec<IronwoodNote>,
        outgoing_ironwood_notes: Vec<OutgoingIronwoodNote>,
    ) -> Self {
        let mut transaction = Self::new_for_test(txid, status);
        transaction.ironwood_notes = ironwood_notes;
        transaction.outgoing_ironwood_notes = outgoing_ironwood_notes;
        transaction
    }
}

#[cfg(any(test, feature = "test-features"))]
impl SyncState {
    /// Creates sync state with the given scan ranges, for tests exercising
    /// spendability/witness gating without a chain.
    pub fn new_for_test(scan_ranges: Vec<ScanRange>) -> Self {
        let mut sync_state = Self::new();
        sync_state.scan_ranges = scan_ranges;
        sync_state
    }
}

#[cfg(any(test, feature = "test-features"))]
impl<N, Nf: Copy, P> WalletNote<N, Nf, P> {
    /// Creates a minimal received note for testing purposes.
    pub fn new_for_test(
        output_id: OutputId,
        account_id: zip32::AccountId,
        scope: zip32::Scope,
        note: N,
        memo: Memo,
        position: Option<Position>,
    ) -> Self {
        Self {
            output_id,
            key_id: KeyId::from_parts(account_id, scope),
            note,
            nullifier: None,
            position,
            memo,
            spending_transaction: None,
            refetch_nullifier_ranges: Vec::new(),
            marker: std::marker::PhantomData,
        }
    }

    /// Attaches a nullifier, for tests exercising spend paths, since the
    /// spendable-note filter requires a known nullifier.
    #[must_use]
    pub fn with_nullifier_for_test(mut self, nullifier: Nf) -> Self {
        self.nullifier = Some(nullifier);
        self
    }
}

#[cfg(feature = "test-features")]
impl<N, P> OutgoingNote<N, P> {
    /// Creates a minimal outgoing note for testing purposes.
    pub fn new_for_test(
        output_id: OutputId,
        account_id: zip32::AccountId,
        scope: zip32::Scope,
        note: N,
        memo: Memo,
        recipient_full_unified_address: Option<UnifiedAddress>,
    ) -> Self {
        Self {
            output_id,
            key_id: KeyId::from_parts(account_id, scope),
            note,
            memo,
            recipient_full_unified_address,
            marker: std::marker::PhantomData,
        }
    }
}

#[cfg(feature = "wallet_essentials")]
impl WalletTransaction {
    /// Returns the total value sent to receivers, excluding value sent to the wallet's own addresses.
    #[must_use]
    pub fn total_value_sent(&self) -> u64 {
        let transparent_value_sent = self
            .transaction
            .transparent_bundle()
            .map_or(0, |bundle| {
                bundle
                    .vout
                    .iter()
                    .map(|output| output.value().into_u64())
                    .sum()
            })
            .saturating_sub(self.total_output_value::<TransparentCoin>());

        let sapling_value_sent =
            self.total_external_outgoing_note_value::<OutgoingSaplingNote, SaplingNote>();
        let orchard_value_sent =
            self.total_external_outgoing_note_value::<OutgoingOrchardNote, OrchardNote>();
        let ironwood_value_sent =
            self.total_external_outgoing_note_value::<OutgoingIronwoodNote, IronwoodNote>();

        transparent_value_sent + sapling_value_sent + orchard_value_sent + ironwood_value_sent
    }

    /// Returns total sum of all output values.
    #[must_use]
    pub fn total_value_received(&self) -> u64 {
        self.total_output_value::<TransparentCoin>()
            + self.total_output_value::<SaplingNote>()
            + self.total_output_value::<OrchardNote>()
            + self.total_output_value::<IronwoodNote>()
    }

    /// Returns total sum of output values for a given pool.
    #[must_use]
    pub fn total_output_value<Op: OutputInterface>(&self) -> u64 {
        Op::transaction_outputs(self)
            .iter()
            .map(OutputInterface::value)
            .sum()
    }

    /// Returns total sum of outgoing note values for a given shielded pool.
    #[must_use]
    pub fn total_outgoing_note_value<Op: OutgoingNoteInterface>(&self) -> u64 {
        Op::transaction_outgoing_notes(self)
            .iter()
            .map(OutgoingNoteInterface::value)
            .sum()
    }

    /// Returns total sum of outgoing note values for outputs that are not wallet-owned.
    #[must_use]
    pub fn total_external_outgoing_note_value<Outgoing, Incoming>(&self) -> u64
    where
        Outgoing: OutgoingNoteInterface,
        Incoming: OutputInterface,
    {
        Outgoing::transaction_outgoing_notes(self)
            .iter()
            .filter(|outgoing_note| {
                !Incoming::transaction_outputs(self)
                    .iter()
                    .any(|wallet_note| wallet_note.output_id() == outgoing_note.output_id())
            })
            .map(OutgoingNoteInterface::value)
            .sum()
    }
}

impl std::fmt::Debug for WalletTransaction {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.debug_struct("WalletTransaction")
            .field("txid", &self.txid)
            .field("confirmation_status", &self.status)
            .field("datetime", &self.datetime)
            .field("transparent_coins", &self.transparent_coins)
            .field("sapling_notes", &self.sapling_notes)
            .field("orchard_notes", &self.orchard_notes)
            .field("ironwood_notes", &self.ironwood_notes)
            .field("outgoing_sapling_notes", &self.outgoing_sapling_notes)
            .field("outgoing_orchard_notes", &self.outgoing_orchard_notes)
            .field("outgoing_ironwood_notes", &self.outgoing_ironwood_notes)
            .finish()
    }
}

/// Provides a common API for all key identifiers.
pub trait KeyIdInterface {
    /// Account ID.
    fn account_id(&self) -> zip32::AccountId;
}

/// Provides a common API for all output types.
pub trait OutputInterface: Sized {
    /// Identifier for key used to decrypt output.
    type KeyId: KeyIdInterface;
    /// Transaction input type associated with spend detection of output.
    type Input: Clone + Debug + PartialEq + Eq + PartialOrd + Ord;

    /// Output's associated pool type.
    const POOL_TYPE: PoolType;

    /// Output ID.
    fn output_id(&self) -> OutputId;

    /// Identifier for key used to decrypt output.
    fn key_id(&self) -> Self::KeyId;

    /// Transaction ID of transaction this output was spent.
    /// If `None`, output is not spent.
    fn spending_transaction(&self) -> Option<TxId>;

    /// Sets spending transaction.
    fn set_spending_transaction(&mut self, spending_transaction: Option<TxId>);

    /// Note value..
    // TODO: change to Zatoshis checked type
    fn value(&self) -> u64;

    /// Returns the type used to link with transaction inputs for spend detection.
    /// Returns `None` in the case the nullifier is not available for shielded outputs.
    ///
    /// Nullifier for shielded outputs.
    /// Outpoint for transparent outputs.
    fn spend_link(&self) -> Option<Self::Input>;

    /// Inputs within `transaction` used to detect an output's spend status.
    ///
    /// Nullifiers for shielded outputs.
    /// Out points for transparent outputs.
    fn transaction_inputs(transaction: &WalletTransaction) -> Vec<&Self::Input>;

    /// Outputs within `transaction`.
    fn transaction_outputs(transaction: &WalletTransaction) -> &[Self];
}

/// Provides a common API for all shielded output types.
pub trait NoteInterface: OutputInterface {
    /// Decrypted note type.
    type ZcashNote;
    /// Nullifier type.
    type Nullifier: Copy + Clone + PartialEq + Eq + PartialOrd + Ord;

    /// Note's associated shielded protocol.
    const SHIELDED_PROTOCOL: ShieldedPool;

    /// Decrypted note with recipient and value
    fn note(&self) -> &Self::ZcashNote;

    /// Derived nullifier
    fn nullifier(&self) -> Option<Self::Nullifier>;

    /// Commitment tree leaf position
    fn position(&self) -> Option<Position>;

    /// Memo
    fn memo(&self) -> &Memo;

    /// List of block ranges where the nullifiers must be re-fetched to guarantee the note has not been spent.
    /// These scan ranges were marked `ScannedWithoutMapping` or `RefetchingNullifiers` priority before this note was
    /// scanned, meaning the nullifiers were discarded due to memory constraints and will be re-fetched later in the
    /// sync process.
    fn refetch_nullifier_ranges(&self) -> &[Range<BlockHeight>];
}

///  Transparent coin (output) with metadata relevant to the wallet.
#[derive(Debug, Clone)]
pub struct TransparentCoin {
    /// Output ID.
    pub(crate) output_id: OutputId,
    /// Identifier for key used to derive address.
    pub(crate) key_id: TransparentAddressId,
    /// Encoded transparent address.
    pub(crate) address: String,
    /// Script.
    pub(crate) script: Script,
    /// Coin value.
    pub(crate) value: Zatoshis,
    /// Transaction ID of transaction this output was spent.
    /// If `None`, output is not spent.
    pub(crate) spending_transaction: Option<TxId>,
}

#[cfg(feature = "test-features")]
impl TransparentCoin {
    /// Creates a minimal received coin for testing purposes. The script
    /// must be the real locking script for `address`: spendable-output
    /// selection reconstructs the recipient from it and silently drops
    /// coins whose script does not parse to an address.
    pub fn new_for_test(
        output_id: OutputId,
        key_id: TransparentAddressId,
        address: String,
        script: Script,
        value: Zatoshis,
    ) -> Self {
        Self {
            output_id,
            key_id,
            address,
            script,
            value,
            spending_transaction: None,
        }
    }
}

impl TransparentCoin {
    /// Address received to.
    #[must_use]
    pub fn address(&self) -> &str {
        &self.address
    }

    /// Script.
    #[must_use]
    pub fn script(&self) -> &Script {
        &self.script
    }
}

impl OutputInterface for TransparentCoin {
    type KeyId = TransparentAddressId;
    type Input = OutPoint;

    const POOL_TYPE: PoolType = PoolType::Transparent;

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> Self::KeyId {
        self.key_id
    }

    fn spending_transaction(&self) -> Option<TxId> {
        self.spending_transaction
    }

    fn set_spending_transaction(&mut self, spending_transaction: Option<TxId>) {
        self.spending_transaction = spending_transaction;
    }

    fn value(&self) -> u64 {
        self.value.into_u64()
    }

    fn spend_link(&self) -> Option<Self::Input> {
        Some(self.output_id.into())
    }

    fn transaction_inputs(transaction: &WalletTransaction) -> Vec<&Self::Input> {
        transaction.outpoints()
    }

    fn transaction_outputs(transaction: &WalletTransaction) -> &[Self] {
        &transaction.transparent_coins
    }
}

/// The network upgrade at which a shielded pool begins to exist.
///
/// This is the workspace's single pool-to-upgrade mapping: upstream
/// `zcash_protocol` deliberately ships
/// `ShieldedPool` and `NetworkUpgrade` as unrelated enums, so the mapping
/// is defined exactly once, here. Every height clamp involving a pool's
/// existence derives from it. A second mapping anywhere in the workspace
/// is a defect.
#[must_use]
pub fn pool_upgrade(pool: ShieldedPool) -> consensus::NetworkUpgrade {
    match pool {
        ShieldedPool::Sapling => consensus::NetworkUpgrade::Sapling,
        ShieldedPool::Orchard => consensus::NetworkUpgrade::Nu5,
        ShieldedPool::Ironwood => consensus::NetworkUpgrade::Nu6_3,
    }
}

/// A pool's activation height: the block height at which the pool begins
/// to exist on the chain.
///
/// The only constructor is the derivation [`PoolActivation::of`], so a
/// value of this type carries its provenance: it came from the chain's
/// consensus parameters through [`pool_upgrade`], never from arithmetic a
/// call site invented. Seams that must not run without an activation floor
/// (the migration schedule planner, for one) demand this type in their
/// signatures, making floor omission unrepresentable.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PoolActivation(BlockHeight);

impl PoolActivation {
    /// Derives the pool's activation height from the chain's consensus
    /// parameters. `None` when the chain never activates the pool's
    /// upgrade, a real state (regtest schedules may defer an upgrade
    /// indefinitely), in which the pool simply cannot be scheduled
    /// against.
    pub fn of(
        consensus_parameters: &impl consensus::Parameters,
        pool: ShieldedPool,
    ) -> Option<Self> {
        consensus_parameters
            .activation_height(pool_upgrade(pool))
            .map(Self)
    }

    /// The activation height.
    #[must_use]
    pub fn height(&self) -> BlockHeight {
        self.0
    }

    /// The later of the activation and `height`: the effective floor for
    /// heights that must not precede the pool's existence (a wallet
    /// Birthday clamped to the pool's activation, the lower bound of a
    /// scan range). Birthday remains a wallet property throughout. The
    /// pool contributes only its activation height.
    #[must_use]
    pub fn max_with(&self, height: BlockHeight) -> BlockHeight {
        self.0.max(height)
    }

    /// A fabricated activation for tests exercising floor arithmetic
    /// without a full parameter set. Production code has no path here:
    /// the derivation constructor is the only other way in.
    #[cfg(any(test, feature = "test-features"))]
    #[must_use]
    pub fn new_for_test(height: BlockHeight) -> Self {
        Self(height)
    }
}

/// Marker for the Sapling pool, distinguishing note types whose inner data
/// is otherwise identical.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Sapling;

/// Marker for the Orchard pool, distinguishing note types whose inner data
/// is otherwise identical.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Orchard;

/// Marker for the Ironwood pool. Ironwood reuses Orchard's note and
/// nullifier types (note version V3), so without the marker its wallet note
/// type would be the same type as the Orchard one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Ironwood;

/// Wallet note, shielded output with metadata relevant to the wallet. `P` is
/// the pool marker ([`Sapling`], [`Orchard`] or [`Ironwood`]).
#[derive(Debug, Clone)]
pub struct WalletNote<N, Nf: Copy, P> {
    /// Output ID.
    pub(crate) output_id: OutputId,
    /// Identifier for key used to decrypt output.
    pub(crate) key_id: KeyId,
    /// Decrypted note with recipient and value.
    pub(crate) note: N,
    /// Derived nullifier.
    pub(crate) nullifier: Option<Nf>, //TODO: syncing without nullifier deriving key
    /// Commitment tree leaf position.
    pub(crate) position: Option<Position>,
    /// Memo.
    pub(crate) memo: Memo,
    /// Transaction ID of transaction this output was spent.
    /// If `None`, output is not spent.
    pub(crate) spending_transaction: Option<TxId>,
    /// List of block ranges where the nullifiers must be re-fetched to guarantee the note has not been spent.
    /// These scan ranges were marked `ScannedWithoutMapping` or `RefetchingNullifiers` priority before this note was
    /// scanned, meaning the nullifiers were discarded due to memory constraints and will be re-fetched later in the
    /// sync process.
    pub(crate) refetch_nullifier_ranges: Vec<Range<BlockHeight>>,
    /// Pool marker.
    pub(crate) marker: PhantomData<P>,
}

/// Sapling note.
pub type SaplingNote = WalletNote<sapling_crypto::Note, sapling_crypto::Nullifier, Sapling>;

impl OutputInterface for SaplingNote {
    type KeyId = KeyId;
    type Input = sapling_crypto::Nullifier;

    const POOL_TYPE: PoolType = PoolType::Shielded(ShieldedPool::Sapling);

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> KeyId {
        self.key_id
    }

    fn spending_transaction(&self) -> Option<TxId> {
        self.spending_transaction
    }

    fn set_spending_transaction(&mut self, spending_transaction: Option<TxId>) {
        self.spending_transaction = spending_transaction;
    }

    fn value(&self) -> u64 {
        self.note.value().inner()
    }

    fn spend_link(&self) -> Option<Self::Input> {
        self.nullifier
    }

    fn transaction_inputs(transaction: &WalletTransaction) -> Vec<&Self::Input> {
        transaction.sapling_nullifiers()
    }

    fn transaction_outputs(transaction: &WalletTransaction) -> &[Self] {
        &transaction.sapling_notes
    }
}

impl NoteInterface for SaplingNote {
    type ZcashNote = sapling_crypto::Note;
    type Nullifier = Self::Input;

    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Sapling;

    fn note(&self) -> &Self::ZcashNote {
        &self.note
    }

    fn nullifier(&self) -> Option<Self::Nullifier> {
        self.nullifier
    }

    fn position(&self) -> Option<Position> {
        self.position
    }

    fn memo(&self) -> &Memo {
        &self.memo
    }

    fn refetch_nullifier_ranges(&self) -> &[Range<BlockHeight>] {
        &self.refetch_nullifier_ranges
    }
}

/// Orchard note.
pub type OrchardNote = WalletNote<orchard::Note, orchard::note::Nullifier, Orchard>;

impl OutputInterface for OrchardNote {
    type KeyId = KeyId;
    type Input = orchard::note::Nullifier;

    const POOL_TYPE: PoolType = PoolType::Shielded(ShieldedPool::Orchard);

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> KeyId {
        self.key_id
    }

    fn spending_transaction(&self) -> Option<TxId> {
        self.spending_transaction
    }

    fn set_spending_transaction(&mut self, spending_transaction: Option<TxId>) {
        self.spending_transaction = spending_transaction;
    }

    fn value(&self) -> u64 {
        self.note.value().inner()
    }

    fn spend_link(&self) -> Option<Self::Input> {
        self.nullifier
    }

    fn transaction_inputs(transaction: &WalletTransaction) -> Vec<&Self::Input> {
        transaction.orchard_nullifiers()
    }

    fn transaction_outputs(transaction: &WalletTransaction) -> &[Self] {
        &transaction.orchard_notes
    }
}

impl NoteInterface for OrchardNote {
    type ZcashNote = orchard::Note;
    type Nullifier = Self::Input;

    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Orchard;

    fn note(&self) -> &Self::ZcashNote {
        &self.note
    }

    fn nullifier(&self) -> Option<Self::Nullifier> {
        self.spend_link()
    }

    fn position(&self) -> Option<Position> {
        self.position
    }

    fn memo(&self) -> &Memo {
        &self.memo
    }

    fn refetch_nullifier_ranges(&self) -> &[Range<BlockHeight>] {
        &self.refetch_nullifier_ranges
    }
}

/// Ironwood note. Shares Orchard's note and nullifier types (version V3) but
/// belongs to the Ironwood pool with its own note commitment tree.
pub type IronwoodNote = WalletNote<orchard::Note, orchard::note::Nullifier, Ironwood>;

impl OutputInterface for IronwoodNote {
    type KeyId = KeyId;
    type Input = orchard::note::Nullifier;

    const POOL_TYPE: PoolType = PoolType::Shielded(ShieldedPool::Ironwood);

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> KeyId {
        self.key_id
    }

    fn spending_transaction(&self) -> Option<TxId> {
        self.spending_transaction
    }

    fn set_spending_transaction(&mut self, spending_transaction: Option<TxId>) {
        self.spending_transaction = spending_transaction;
    }

    fn value(&self) -> u64 {
        self.note.value().inner()
    }

    fn spend_link(&self) -> Option<Self::Input> {
        self.nullifier
    }

    fn transaction_inputs(transaction: &WalletTransaction) -> Vec<&Self::Input> {
        transaction.ironwood_nullifiers()
    }

    fn transaction_outputs(transaction: &WalletTransaction) -> &[Self] {
        &transaction.ironwood_notes
    }
}

impl NoteInterface for IronwoodNote {
    type ZcashNote = orchard::Note;
    type Nullifier = Self::Input;

    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Ironwood;

    fn note(&self) -> &Self::ZcashNote {
        &self.note
    }

    fn nullifier(&self) -> Option<Self::Nullifier> {
        self.spend_link()
    }

    fn position(&self) -> Option<Position> {
        self.position
    }

    fn memo(&self) -> &Memo {
        &self.memo
    }

    fn refetch_nullifier_ranges(&self) -> &[Range<BlockHeight>] {
        &self.refetch_nullifier_ranges
    }
}

/// Provides a common API for all outgoing note types.
pub trait OutgoingNoteInterface: Sized {
    /// Decrypted note type.
    type ZcashNote;
    /// Address type.
    type Address: Clone + Copy + Debug + PartialEq + Eq;
    /// Encoding error
    type Error: Debug + std::error::Error;

    /// Note's associated shielded protocol.
    const SHIELDED_PROTOCOL: ShieldedPool;

    /// Output ID.
    fn output_id(&self) -> OutputId;

    /// Identifier for key used to decrypt outgoing note.
    fn key_id(&self) -> KeyId;

    /// Note value.
    fn value(&self) -> u64;

    /// Decrypted note with recipient and value.
    fn note(&self) -> &Self::ZcashNote;

    /// Memo.
    fn memo(&self) -> &Memo;

    /// Recipient address.
    fn recipient(&self) -> Self::Address;

    /// Recipient unified address as given by recipient and recorded in an encoded memo (all original receivers).
    fn recipient_full_unified_address(&self) -> Option<&UnifiedAddress>;

    /// Encoded recipient address recorded in note on chain (single receiver).
    fn encoded_recipient<P>(&self, parameters: &P) -> Result<String, Self::Error>
    where
        P: consensus::Parameters + consensus::NetworkConstants;

    /// Encoded recipient unified address as given by recipient and recorded in an encoded memo (all original receivers).
    fn encoded_recipient_full_unified_address<P>(&self, consensus_parameters: &P) -> Option<String>
    where
        P: consensus::Parameters + consensus::NetworkConstants;

    /// Outgoing notes within `transaction`.
    fn transaction_outgoing_notes(transaction: &WalletTransaction) -> &[Self];
}

/// Note sent from this capability to a recipient. `P` is the pool marker
/// ([`Sapling`], [`Orchard`] or [`Ironwood`]).
#[derive(Debug, Clone, PartialEq)]
pub struct OutgoingNote<N, P> {
    /// Output ID.
    pub(crate) output_id: OutputId,
    /// Identifier for key used to decrypt output.
    pub(crate) key_id: KeyId,
    /// Decrypted note with recipient and value.
    pub(crate) note: N,
    /// Memo.
    pub(crate) memo: Memo,
    /// Recipient's full unified address from encoded memo.
    pub(crate) recipient_full_unified_address: Option<UnifiedAddress>,
    /// Pool marker.
    pub(crate) marker: PhantomData<P>,
}

/// Outgoing sapling note.
pub type OutgoingSaplingNote = OutgoingNote<sapling_crypto::Note, Sapling>;

impl OutgoingNoteInterface for OutgoingSaplingNote {
    type ZcashNote = sapling_crypto::Note;
    type Address = sapling_crypto::PaymentAddress;
    type Error = Infallible;

    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Sapling;

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> KeyId {
        self.key_id
    }

    fn value(&self) -> u64 {
        self.note.value().inner()
    }

    fn note(&self) -> &Self::ZcashNote {
        &self.note
    }

    fn memo(&self) -> &Memo {
        &self.memo
    }

    fn recipient(&self) -> Self::Address {
        self.note.recipient()
    }

    fn recipient_full_unified_address(&self) -> Option<&UnifiedAddress> {
        self.recipient_full_unified_address.as_ref()
    }

    fn encoded_recipient<P>(&self, consensus_parameters: &P) -> Result<String, Self::Error>
    where
        P: consensus::Parameters + consensus::NetworkConstants,
    {
        Ok(encode_payment_address(
            zcash_address::constants::hrp_sapling_payment_address(
                consensus_parameters.network_type(),
            ),
            &self.note().recipient(),
        ))
    }

    fn encoded_recipient_full_unified_address<P>(&self, consensus_parameters: &P) -> Option<String>
    where
        P: consensus::Parameters + consensus::NetworkConstants,
    {
        self.recipient_full_unified_address
            .as_ref()
            .map(|unified_address| unified_address.encode(consensus_parameters))
    }

    fn transaction_outgoing_notes(transaction: &WalletTransaction) -> &[Self] {
        &transaction.outgoing_sapling_notes
    }
}

/// Outgoing orchard note.
pub type OutgoingOrchardNote = OutgoingNote<orchard::Note, Orchard>;

impl OutgoingNoteInterface for OutgoingOrchardNote {
    type ZcashNote = orchard::Note;
    type Address = orchard::Address;
    type Error = ParseError;

    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Orchard;

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> KeyId {
        self.key_id
    }

    fn value(&self) -> u64 {
        self.note.value().inner()
    }

    fn note(&self) -> &Self::ZcashNote {
        &self.note
    }

    fn memo(&self) -> &Memo {
        &self.memo
    }

    fn recipient(&self) -> Self::Address {
        self.note.recipient()
    }

    fn recipient_full_unified_address(&self) -> Option<&UnifiedAddress> {
        self.recipient_full_unified_address.as_ref()
    }

    fn encoded_recipient<P>(&self, parameters: &P) -> Result<String, Self::Error>
    where
        P: consensus::Parameters + consensus::NetworkConstants,
    {
        keys::encode_orchard_receiver(parameters, &self.note().recipient())
    }

    fn encoded_recipient_full_unified_address<P>(&self, consensus_parameters: &P) -> Option<String>
    where
        P: consensus::Parameters + consensus::NetworkConstants,
    {
        self.recipient_full_unified_address
            .as_ref()
            .map(|unified_address| unified_address.encode(consensus_parameters))
    }

    fn transaction_outgoing_notes(transaction: &WalletTransaction) -> &[Self] {
        &transaction.outgoing_orchard_notes
    }
}

/// Outgoing ironwood note. Shares Orchard's note and receiver types.
pub type OutgoingIronwoodNote = OutgoingNote<orchard::Note, Ironwood>;

impl OutgoingNoteInterface for OutgoingIronwoodNote {
    type ZcashNote = orchard::Note;
    type Address = orchard::Address;
    type Error = ParseError;

    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Ironwood;

    fn output_id(&self) -> OutputId {
        self.output_id
    }

    fn key_id(&self) -> KeyId {
        self.key_id
    }

    fn value(&self) -> u64 {
        self.note.value().inner()
    }

    fn note(&self) -> &Self::ZcashNote {
        &self.note
    }

    fn memo(&self) -> &Memo {
        &self.memo
    }

    fn recipient(&self) -> Self::Address {
        self.note.recipient()
    }

    fn recipient_full_unified_address(&self) -> Option<&UnifiedAddress> {
        self.recipient_full_unified_address.as_ref()
    }

    fn encoded_recipient<P>(&self, parameters: &P) -> Result<String, Self::Error>
    where
        P: consensus::Parameters + consensus::NetworkConstants,
    {
        keys::encode_orchard_receiver(parameters, &self.note().recipient())
    }

    fn encoded_recipient_full_unified_address<P>(&self, consensus_parameters: &P) -> Option<String>
    where
        P: consensus::Parameters + consensus::NetworkConstants,
    {
        self.recipient_full_unified_address
            .as_ref()
            .map(|unified_address| unified_address.encode(consensus_parameters))
    }

    fn transaction_outgoing_notes(transaction: &WalletTransaction) -> &[Self] {
        &transaction.outgoing_ironwood_notes
    }
}

/// Reduces the wallet to what a build that never tracked `pool` would have
/// left behind: the very same scanned ranges, and none of that pool's data.
///
/// This is the state a wallet reaches by syncing across a pool's activation
/// on a build that predates the pool, which is not otherwise constructible
/// from outside. Scan-range priorities are deliberately untouched, since the
/// defect being reproduced is precisely that the ranges still claim to be
/// scanned.
#[cfg(any(test, feature = "test-features"))]
pub fn strip_pool_tracking_for_test<W>(wallet: &mut W, pool: ShieldedPool) -> Result<(), W::Error>
where
    W: traits::SyncWallet
        + traits::SyncBlocks
        + traits::SyncTransactions
        + traits::SyncNullifiers
        + traits::SyncShardTrees,
{
    for block in wallet.get_wallet_blocks_mut()?.values_mut() {
        let tree_bounds = &mut block.tree_bounds;
        match pool {
            ShieldedPool::Sapling => {
                tree_bounds.sapling_initial_tree_size = 0;
                tree_bounds.sapling_final_tree_size = 0;
            }
            ShieldedPool::Orchard => {
                tree_bounds.orchard_initial_tree_size = 0;
                tree_bounds.orchard_final_tree_size = 0;
            }
            ShieldedPool::Ironwood => {
                tree_bounds.ironwood_initial_tree_size = 0;
                tree_bounds.ironwood_final_tree_size = 0;
            }
        }
    }
    for transaction in wallet.get_wallet_transactions_mut()?.values_mut() {
        match pool {
            ShieldedPool::Sapling => {
                transaction.sapling_notes.clear();
                transaction.outgoing_sapling_notes.clear();
            }
            ShieldedPool::Orchard => {
                transaction.orchard_notes.clear();
                transaction.outgoing_orchard_notes.clear();
            }
            ShieldedPool::Ironwood => {
                transaction.ironwood_notes.clear();
                transaction.outgoing_ironwood_notes.clear();
            }
        }
    }

    let nullifiers = wallet.get_nullifiers_mut()?;
    match pool {
        ShieldedPool::Sapling => nullifiers.sapling.clear(),
        ShieldedPool::Orchard => nullifiers.orchard.clear(),
        ShieldedPool::Ironwood => nullifiers.ironwood.clear(),
    }

    let empty = ShardTrees::new();
    let shard_trees = wallet.get_shard_trees_mut()?;
    match pool {
        ShieldedPool::Sapling => shard_trees.sapling = empty.sapling,
        ShieldedPool::Orchard => shard_trees.orchard = empty.orchard,
        ShieldedPool::Ironwood => shard_trees.ironwood = empty.ironwood,
    }

    let sync_state = wallet.get_sync_state_mut()?;
    match pool {
        ShieldedPool::Sapling => sync_state.sapling_shard_ranges.clear(),
        ShieldedPool::Orchard => sync_state.orchard_shard_ranges.clear(),
        ShieldedPool::Ironwood => sync_state.ironwood_shard_ranges.clear(),
    }

    Ok(())
}

// TODO: allow consumer to define shard store. memory shard store has infallible error type but other may not so error
// handling will need to replace expects
/// Type alias for sapling memory shard store
pub type SaplingShardStore = MemoryShardStore<sapling_crypto::Node, BlockHeight>;

/// Type alias for orchard memory shard store
pub type OrchardShardStore = MemoryShardStore<MerkleHashOrchard, BlockHeight>;

/// Shard tree wallet data struct
#[derive(Debug)]
pub struct ShardTrees {
    /// Sapling shard tree
    pub sapling: ShardTree<
        SaplingShardStore,
        { sapling_crypto::NOTE_COMMITMENT_TREE_DEPTH },
        { witness::SHARD_HEIGHT },
    >,
    /// Orchard shard tree
    pub orchard: ShardTree<
        OrchardShardStore,
        { orchard::NOTE_COMMITMENT_TREE_DEPTH as u8 },
        { witness::SHARD_HEIGHT },
    >,
    /// Ironwood shard tree. Ironwood reuses the Orchard note commitment tree
    /// structure (same hash and depth), so it has the same shape as `orchard`.
    pub ironwood: ShardTree<
        OrchardShardStore,
        { orchard::NOTE_COMMITMENT_TREE_DEPTH as u8 },
        { witness::SHARD_HEIGHT },
    >,
}

impl ShardTrees {
    /// Create new `ShardTrees`
    #[must_use]
    pub fn new() -> Self {
        Self {
            sapling: empty_shard_tree(),
            orchard: empty_shard_tree(),
            ironwood: empty_shard_tree(),
        }
    }

    /// Replaces one pool's shard tree with an empty tree, leaving the other
    /// pools alone.
    ///
    /// The empty tree is that pool's correct state at its own activation, so
    /// this is the rollback a pool needs when its recorded history cannot be
    /// trusted and no checkpoint survives to roll back to.
    pub(crate) fn clear_pool(&mut self, pool: ShieldedPool) {
        tracing::info!("Clearing {pool:?} shard tree.");
        match pool {
            ShieldedPool::Sapling => self.sapling = empty_shard_tree(),
            ShieldedPool::Orchard => self.orchard = empty_shard_tree(),
            ShieldedPool::Ironwood => self.ironwood = empty_shard_tree(),
        }
    }
}

impl Default for ShardTrees {
    fn default() -> Self {
        Self::new()
    }
}

/// An empty shard tree with the crate's standard checkpoint retention and
/// the zero-height checkpoint that every fresh tree must carry.
pub(crate) fn empty_shard_tree<H, const DEPTH: u8, const SHARD_HEIGHT: u8>()
-> ShardTree<MemoryShardStore<H, BlockHeight>, DEPTH, SHARD_HEIGHT>
where
    H: incrementalmerkletree::Hashable + Clone + PartialEq,
{
    let mut tree = ShardTree::new(
        MemoryShardStore::empty(),
        SHARDTREE_CHECKPOINT_ROLLING_WINDOW_SIZE as usize,
    );

    // `NotAboveNewest` is impossible on an empty checkpoint store.
    assert_eq!(
        tree.append_checkpoint(BlockHeight::from_u32(0))
            .expect("should never fail"),
        CheckpointAppendOutcome::Appended
    );

    tree
}

use shardtree::store::ShardStore;

pub(crate) trait SyncDomain {
    const SHIELDED_PROTOCOL: ShieldedPool;

    type Note: NoteInterface;
    type ShardStore: ShardStore<CheckpointId = BlockHeight>;

    fn notes_mut(wallet_transaction: &mut WalletTransaction) -> Vec<&mut Self::Note>;
}

impl SyncDomain for Sapling {
    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Sapling;

    type Note = SaplingNote;
    type ShardStore = SaplingShardStore;

    fn notes_mut(wallet_transaction: &mut WalletTransaction) -> Vec<&mut Self::Note> {
        wallet_transaction.sapling_notes_mut()
    }
}

impl SyncDomain for Orchard {
    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Orchard;

    type Note = OrchardNote;
    type ShardStore = OrchardShardStore;

    fn notes_mut(wallet_transaction: &mut WalletTransaction) -> Vec<&mut Self::Note> {
        wallet_transaction.orchard_notes_mut()
    }
}

impl SyncDomain for Ironwood {
    const SHIELDED_PROTOCOL: ShieldedPool = ShieldedPool::Ironwood;

    type Note = IronwoodNote;
    // Ironwood reuses the Orchard note commitment tree hash, so the same
    // store type serves its (separate) tree.
    type ShardStore = OrchardShardStore;

    fn notes_mut(wallet_transaction: &mut WalletTransaction) -> Vec<&mut Self::Note> {
        wallet_transaction.ironwood_notes_mut()
    }
}

#[cfg(test)]
mod test {
    use zcash_protocol::TxId;
    use zcash_protocol::consensus::BlockHeight;
    use zingo_status::confirmation_status::ConfirmationStatus;

    use super::WalletTransaction;

    fn transaction_with_status(status: ConfirmationStatus) -> WalletTransaction {
        WalletTransaction::new_for_test(TxId::from_bytes([0; 32]), status)
    }

    #[test]
    fn update_status_follows_transaction_lifecycle() {
        let mut transaction =
            transaction_with_status(ConfirmationStatus::Calculated(BlockHeight::from_u32(10)));

        transaction.update_status(
            ConfirmationStatus::Transmitted(BlockHeight::from_u32(10)),
            1,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Transmitted(_)
        ));

        transaction.update_status(
            ConfirmationStatus::Mempool(BlockHeight::from_u32(11)),
            2,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Mempool(_)
        ));

        transaction.update_status(
            ConfirmationStatus::Confirmed(BlockHeight::from_u32(11)),
            3,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Confirmed(_)
        ));
    }

    #[test]
    fn update_status_failed_returns_to_mempool() {
        let mut transaction =
            transaction_with_status(ConfirmationStatus::Failed(BlockHeight::from_u32(10)));

        transaction.update_status(
            ConfirmationStatus::Mempool(BlockHeight::from_u32(11)),
            1,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Mempool(_)
        ));
    }

    #[test]
    fn update_status_failed_is_not_directly_confirmable() {
        // confirming a failed transaction is handled by replacing the whole record during block
        // scanning, not by a status update.
        let mut transaction =
            transaction_with_status(ConfirmationStatus::Failed(BlockHeight::from_u32(10)));

        transaction.update_status(
            ConfirmationStatus::Confirmed(BlockHeight::from_u32(11)),
            1,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Failed(_)
        ));
    }

    #[test]
    fn update_status_confirmed_is_terminal() {
        let mut transaction =
            transaction_with_status(ConfirmationStatus::Confirmed(BlockHeight::from_u32(10)));

        transaction.update_status(
            ConfirmationStatus::Mempool(BlockHeight::from_u32(11)),
            1,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Confirmed(_)
        ));

        transaction.update_status(
            ConfirmationStatus::Failed(BlockHeight::from_u32(11)),
            2,
            false,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Confirmed(_)
        ));
    }

    #[test]
    fn update_status_forces_confirmed_to_fail() {
        let mut transaction =
            transaction_with_status(ConfirmationStatus::Confirmed(BlockHeight::from_u32(10)));

        transaction.update_status(
            ConfirmationStatus::Failed(BlockHeight::from_u32(11)),
            2,
            true,
        );
        assert!(matches!(
            transaction.status(),
            ConfirmationStatus::Failed(_)
        ));
    }
}